# ConnectCloud Trade API (v1.0.0)

Offers, orders, invoices and credit notes, contracts, purchase orders and goods receipts, inbound invoices with their checks, MSP and ITSP (distributor catalog) and the trade settings.

Base URLs:

- Production: `https://api.mbcom.cloud`
- Staging: `https://api.mbcom.cloud`
- Sandbox: `https://developers.mbcom.cloud/sandbox/trade`

Trade holds the commercial documents of a tenant ("Vorgänge"): outgoing offers, order
confirmations, delivery notes, invoices and credit notes, purchase orders and goods receipts,
and inbound (supplier) invoices that arrive through the DMS and are checked against purchase
orders. It also keeps service contracts, collects MSP usage for billing, searches distributor
catalogs (ITSP) and serves the public offer portal in which customers accept offers.

## Model
- **Transactions** are all commercial documents in one shape (`Transaction`): a header with
  partner, totals, payment terms and `items` (lines). `transactionType` names the type from the
  tenant's **transaction type catalogue** (`OFFER`, `ORDER`, `DELIVERY_NOTE`, `INVOICE`,
  `CREDIT_NOTE`, `PURCHASE_ORDER`, `INBOUND_INVOICE`, `GOODS_RECEIPT` and the tenant's own types);
  each type has a direction (`OUT` sales, `IN` purchasing), a number prefix and optionally an
  e-invoice document type code (UNTDID 1001, BT-3).
- Header totals are computed from the lines when a document is saved: lines of position type
  `normal` and selected `optional` lines count; `title`, `subtotal` and `text` lines do not.
- `predecessorId` is the previous **version** of the same document (`POST …/revision`);
  `sourceTransactionId` is the document this one was made from (offer → order, purchase order →
  goods receipt or matched inbound invoice).
- **Payment terms** (`paymentTermCode`, `netDays`, `skonto*`, `paymentTermsText`) are a snapshot
  taken when a document is created: the partner's terms from masterdata, else the tenant default
  (`outbound.defaultPaymentTerms`, not for purchase orders). Later masterdata changes never alter it.
- Every change of a transaction is recorded in its **protocol** (Verlauf): who, when, the action,
  the status change and the changed fields and lines. Entries outlive a deleted document.
- **Purchase orders** (`draft → open → partially_received → received`, or `closed` / `cancelled`)
  receive **goods receipts**; a receipt raises the received quantities of the order lines.
- **Inbound invoices** are created from DMS documents, read from the e-invoice XML (XRechnung,
  ZUGFeRD) or by OCR and AI extraction, enriched with masterdata and matched against purchase
  orders and goods receipts (3-way match). Status flow: `RECEIVED → OCR_DONE → EXTRACTED →
  MATCHED | DISCREPANCY | DUPLICATE`, then `IN_REVIEW`, `RELEASED` or `REJECTED`; `FAILED` when
  processing failed. **Lock reasons** (`lockReasons`, e.g. `PREISABWEICHUNG`, `DUPLIKAT`,
  `FEHLENDE_BESTELLUNG`) with `isBlocking: true` block the release unless it is overridden with a comment.
- **Contracts** are customer or supplier contracts with billing cadence, optional hour
  contingents and back-to-back links between a customer and a supplier contract.
- **Offer portal**: the recipient of an offer opens it with a link token, confirms their e-mail
  with a one-time code and accepts it; the accepted offer is frozen and converted into an order.

## Authentication
Send an access token as `Authorization: Bearer <accessToken>`. Get it by exchanging an API key at
`POST https://api.mbcom.cloud/api/hr/v1/auth/token`; it lives 15 minutes and carries the key's permissions.
The tenant is always the one of the token. Guide: https://developers.mbcom.cloud/guides/authentication

## Permissions
Every tenant route names the permission it needs (summaries in parentheses); a valid token with an active tenant
alone opens only `getConfigStatus` and `getMspStatus`. The documents are split by area, each with a read and a
write permission:

| Permission | Grants |
|---|---|
| `tenant:trade:sales:read` / `:write` | outgoing documents: offers, order confirmations, delivery notes, invoice and credit note drafts (`/sales/*`), the snapshot API (`/invoices`, `/offers`, `/orders`, `/delivery-notes`), the issue preview, order fulfilment and supply, offer invitations, e-invoice checks |
| `tenant:trade:purchasing:read` / `:write` | purchase orders, goods receipts, supplier delivery notes, reading purchase recommendations and carts, the distributor catalog (`/itsp/articles/*` search, details, enrichment, product groups, units) |
| `tenant:trade:inbound:read` / `:write` | inbound invoices: list, read, record, correct, match, reprocess, accept and withdraw lock reasons |
| `tenant:trade:inbound:approve` | release, reject and reopen inbound invoices |
| `tenant:trade:contract:read` / `:write` | contracts and back-to-back links (the recurring positions of a contract are MSP's: read also with `tenant:trade:msp:read`, written with `tenant:trade:msp:write`) |
| `tenant:trade:msp:read` / `:write` / `:approve` | MSP billing: runs, usage, mappings, provider customers and reconciliation (read); collecting, mapping, report upload and contract positions (write); computing, delivery and approving the invoices (approve) |
| `tenant:trade:invoice:issue` | issue a draft invoice or credit note (number it, validate and archive the XRechnung, mail it: `issueInvoiceDraft`), release a reviewed draft (`releaseTransaction`), record an issued invoice |
| `tenant:settings:read` | read the trade, MSP and ITSP configuration (secrets masked), EGIS supplier mapping, supplier addresses, article check of the inbound settings |
| `tenant:settings:write` | change the configuration, test connector credentials, change the transaction type catalogue, record service usage |
| `tenant:delivery-note:post` | post the goods receipt of a supplier delivery note |
| `tenant:egis-cart:write` | list, read and fill the tenant's shared EGIS shopping carts, delete one |
| `tenant:egis-order:send` | send a purchase order to its distributor through EGIS, check what is missing, refresh its EGIS state |
| `tenant:stock:read` | stock levels (on hand, reserved, on order, available), minimum-stock rules and the movement history |
| `tenant:stock:write` | set or remove a minimum-stock rule, book a stock correction or an inventory count |
| `tenant:purchase-order:send` | send a purchase order to its supplier through every other channel than EGIS (distributor API, mail, recorded as ordered by hand), check what is missing, mail it again after a change, read its distributor state now |
| `tenant:purchase-recommendation:write` | dismiss, restore and recompute purchase recommendations |
| `tenant:purchase-cart:write` | create, change, optimize and discard purchase carts, cancel a sales order together with its purchase order drafts (`cancelOrderConfirmation`), accept a proposal (creates the purchase orders) and send them; sending each order also needs its channel's permission (`tenant:egis-order:send` for EGIS, `tenant:purchase-order:send` for every other channel) |

The generic transaction routes (`/sales/transactions*`) serve every document type: the route takes the read (or
write) permission of any area and decides per document – inbound invoices need the inbound permission, documents of
direction `OUT` the sales one, `IN` the purchasing one; lists leave out what the caller may not read. The transaction
type catalogue is read with any trade read permission or `tenant:settings:read`.

ITSP article creation, product groups, units and supplier addresses forward the caller's token to
masterdata, which checks its own permissions (e.g. `tenant:masterdata:write` to create an article).

## Conventions
- Paths are absolute (`servers: /`): trade serves its whole API under `/api/trade/v1` – the distributor
  catalog under `/api/trade/v1/itsp`, the inbound invoice settings of the portal under `/api/trade/v1/inbound`.
  The former prefixes (`/api/trade/…` without version, `/api/…` such as `/api/sales/…`, `/api/contracts`,
  `/api/msp/…`, `/api/public/offers/…`, and `/api/itsp/v1`, `/api/invoice/v1`) are gone and answer 404.
- Lists answer the envelope `{items, total?, nextCursor?}`, never a bare array. Lists that grow without bound –
  transactions, contracts, purchase orders, goods receipts, inbound invoices, inbound delivery notes, e-invoice
  checks and stock movements – page by keyset: pass the `nextCursor` of a page as `cursor` to get the next one
  (newest first, the id breaks ties; absent on the last page). The lists the portal pages by number also count
  `total` on every page. An invalid `limit` or `cursor` is a `400 invalid`, never clamped.
- Errors have the shape `{error, code, field?, missingFields?, details?}` (`Error`, guide „Errors“). `error` is
  a message, often in German for end users; branch on the snake_case `code`. Validation is `400 invalid`
  (`field`, `details.fields`), a business rule refusal `422` with its own code, an unexpected failure `500
  internal` (no details). Extra facts of an answer sit in `details` (`preview`, `problems`, `findings`,
  `report`, `purchaseOrders`, …). `401` answers have no body.
- **Workflow lock**: while a workflow runs on a transaction (`metadata.workflow.state` `OPEN` or
  `RETRYING_SYNC`), writes to it answer `423 workflow_locked`. `metadata.workflow` is owned by the
  workflow module; an update never changes it.
- Secrets in configuration answers are masked (`••••••••`); sending the mask or an empty value back
  keeps the stored secret.
- There is no optimistic locking: `PUT` replaces the stored values with the request body.

## Events
Published through the transactional outbox: `trade.transaction.created|updated|deleted`
(`transactionId`, `transactionType`, `transactionNumber`, `version`, `status`, `netTotal`,
`grossTotal`), `trade.invoice.issued`, `trade.invoice.released` (`releaseTransaction`: the transaction fields plus
`taxTotal`, `documentDate`, `invoiceRole`, `actorKind`), `trade.invoice.validation_failed` (`validationId`,
`invoiceId`, `invoiceNumber`, `source`, `mode`, `errorCount`, `warningCount`, `rules`, `validatedAt`; an issued
invoice whose e-invoice check failed), `trade.msp.invoice.created` (`invoiceId`, `year`, `month`, `addressId`,
`netTotal`, `transactionId`, `transactionNumber`; an approved MSP invoice booked in Verkauf),
`trade.contract.quota_posted` (`key`, `contractId`, `potId`, `hours`, `workDate`), `trade.offer.created`,
`trade.order.created`,
`trade.deliverynote.created` (`deliveryNoteId`, `deliveryNoteNumber`, `addressId`; `orderId` for a note made from an
order), `trade.deliverynote.cancelled` (`deliveryNoteId`, `deliveryNoteNumber`, `orderId`), `trade.usage.recorded`, `trade.contract.created|updated|deleted`,
`trade.purchaseorder.created|updated`, `trade.purchaseorder.sent` (`purchaseOrderId`, `poNumber`, `channel`,
`orderNumber`; sent to the supplier by API, mail or recorded as ordered by hand), `trade.goodsreceipt.created`,
`trade.inboundinvoice.created|extracted|matched|blocked|duplicate|released|reopened|rejected|failed`
(`inboundInvoiceId`, `status`, `previousStatus`, `actor`, `comment`; `released` also carries `override`, and
`autoRelease: true` and the applied `rule` when the system released the invoice – neither is sent on a release by a
person),
`trade.inbounddeliverynote.created|extracted|posted|rejected|failed` (`deliveryNoteId`, `status`; supplier delivery
notes, #924; `posted` also carries `goodsReceiptId`, `grNumber` and `auto` – `true` when the system posted the goods
receipt, `false` for a person),
`trade.stock.below_minimum` (`articleId`, `warehouseId`, `available`, `minStock`, `onHand`, `reserved`, `onOrder`; once per crossing below the minimum),
`trade.purchase_recommendations.changed` (`opened`, `updated`, `closed`; after a recompute that changed recommendations),
`trade.purchase_cart.accepted` (`cartId`, `proposalId`, `purchaseOrderIds`; once per accepted proposal that created purchase orders),
`trade.order.supply_changed` (`orderId`, `orderNumber`, `purchaseOrderId`, `poNumber`, `goodsReceiptId`, `grNumber`,
`dropShip`, `complete`, `lines` [`orderLineId`, `quantity` (of the order line), `receiptQty` (of this receipt),
`receivedQty`, `deliveredQty`]; one per sales order a goods receipt brought goods for, named by its newest revision),
`trade.order.dropship_delivered` (`orderId`, `orderNumber`, `purchaseOrderId`, `poNumber`, `goodsReceiptId`,
`grNumber`, `deliveryNoteId` (empty for a receipt by hand), `trackingNumbers`, `shipTo` (the customer's delivery
address: the purchase order's drop-ship snapshot, else the order's ship-to), `lines` [`orderLineId`,
`quantity` delivered by this receipt]; one per sales order a drop-ship receipt delivered to),
`trade.order.cancelled` (`orderId`, `orderNumber`, `cancelledPurchaseOrderIds`, `cancelledPurchaseOrders`,
`openPurchaseOrderIds`, `openPurchaseOrders`, `deletedRecommendations`, `flaggedCartLines`),
`trade.offer.invitation_created` (`sessionId`, `transactionId`, `recipientEmail`, `recipientName`, `expiresAt`;
never the link's token), `trade.offer.otp_requested` (`tokenSessionId`, `transactionId`, `email`, `expiresAt`;
never the code), `trade.offer.evidence_recorded|accepted`. The link and the code go to the recipient alone, by
mail through comms (templates `trade.offer_invitation`, `trade.offer_code`).

# Transactions

## List transactions (tenant:trade:sales|purchasing|inbound:read by document type)

`GET /api/trade/v1/sales/transactions`

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

Newest first. Without filters every type is listed; lists contain the lines only where the store loads them.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `search` | query | string |  | Substring of the number, the partner's number or the partner name (case-insensitive). |
| `type` | query | string |  | Transaction type code. |
| `direction` | query | string |  | Only types of this direction (case-insensitive). (one of `IN`, `OUT`) |
| `status` | query | string |  | Exact status. |
| `number` | query | string |  | Exact transaction number (case-insensitive, trimmed). |
| `source` | query | string (uuid) |  | Only documents made from this document or any revision of it (its delivery notes, the invoices listing them in `typeData.sources`, credit notes of an invoice). |
| `opportunityId` | query | string (uuid) |  | Only documents of this crm opportunity (`opportunityId`; a value that is no UUID matches nothing). |
| `limit` | query | integer |  | Page size; at most 500. (default `50`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** A page of transactions, newest first (creation time, then id); `nextCursor` continues it. (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `items` (array of Transaction, required)
  - `addressId` (string (uuid)): Masterdata address of the partner.
  - `createdAt` (string (date-time), read-only): When the transaction was created.
  - `currency` (string): ISO 4217; EUR when empty.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `deliveryDate` (string (date-time)): Delivery date.
  - `documentDate` (string (date-time)): Today when empty on create.
  - `documentRefId` (string (uuid)): DMS document of the transaction.
  - `dueDate` (string (date-time)): Due date.
  - `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
  - `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
  - `exchangeRate` (number): 1 when empty.
  - `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
  - `footerText` (string): Text printed below the lines.
  - `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
  - `grossTotal` (number, read-only): Gross total, computed from the lines.
  - `headerText` (string): Text printed above the lines.
  - `id` (string (uuid), read-only): Id of the transaction.
  - `items` (array of TransactionLine): Lines; on update they replace all lines when present.
    - `name` (string, required): Name of the article or line.
    - `quantity` (number, required): Quantity.
    - `articleNumber` (string): Article number in masterdata.
    - `createdAt` (string (date-time), read-only): When the line was created.
    - `description` (string): Description of the line.
    - `discountPercent` (number): Discount in percent.
    - `ean` (string): EAN (GTIN) of the article.
    - `id` (string (uuid), read-only): Id of the line.
    - `isOptional` (boolean): The line is optional (position type `optional`).
    - `isSelected` (boolean): Selected optional lines count in the totals.
    - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
    - `mpn` (string): Manufacturer part number.
    - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
    - `positionNumber` (integer, read-only): Set from the order of `items`.
    - `positionType` (PositionType)
    - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
    - `productId` (string (uuid)): Masterdata article (product) id.
    - `sortOrder` (integer): Sort order (ascending).
    - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
    - `taxRate` (number): Percent.
    - `totalPriceGross` (number, read-only): Gross total of the line, computed.
    - `totalPriceNet` (number, read-only): Net total of the line, computed.
    - `transactionId` (string (uuid), read-only): Id of the transaction.
    - `unit` (string): Unit of measure.
    - `unitPriceNet` (number): Negative for a credit position.
    - `updatedAt` (string (date-time), read-only): When the line was last changed.
  - `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number, read-only): Computed from the lines.
  - `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
  - `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
  - `partnerReference` (string): The partner's order reference (BT-13).
  - `paymentMethodCode` (string): Code of the payment method in masterdata.
  - `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
  - `paymentTermsText` (string): Payment terms as printed text.
  - `predecessorId` (string (uuid)): Previous version of the same document.
  - `recipientAddress` (object): Address snapshot of the partner.
  - `recipientCompany` (string): Company of the recipient.
  - `recipientEmail` (string): E-mail of the recipient.
  - `recipientName` (string): Name of the recipient.
  - `skontoDays1` (integer): Days of the first cash discount.
  - `skontoDays2` (integer): Days of the second cash discount.
  - `skontoRate1` (number): Rate in percent of the first cash discount.
  - `skontoRate2` (number): Rate in percent of the second cash discount.
  - `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
  - `sourceTransactionId` (string (uuid)): Document this one was made from.
  - `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
  - `taxTotal` (number, read-only): Tax total, computed from the lines.
  - `tenantName` (string, read-only): Name of the tenant.
  - `transactionNumber` (string): Assigned with the type's prefix when empty on create.
  - `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
  - `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
  - `updatedAt` (string (date-time), read-only): When the transaction was last changed.
  - `validUntil` (string (date-time)): Offers only.
  - `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
      "createdAt": "2026-11-18T08:20:00Z",
      "currency": "EUR",
      "documentDate": "2026-11-19T00:00:00Z",
      "dueDate": "2026-12-19T00:00:00Z",
      "eInvoiceValidation": {
        "createdAt": "2026-11-19T09:05:00Z",
        "errorCount": 0,
        "id": "7c0d1e2f-3a4b-4c5d-8e6f-8a9b0c1d2e01",
        "valid": true,
        "warningCount": 1
      },
      "grossTotal": 2464.49,
      "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "netTotal": 2071,
      "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "status": "ISSUED",
      "taxTotal": 393.49,
      "transactionNumber": "RE-2026-0398",
      "transactionType": "INVOICE",
      "updatedAt": "2026-11-19T09:05:00Z",
      "version": 1
    },
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
      "createdAt": "2026-11-17T07:45:00Z",
      "currency": "EUR",
      "documentDate": "2026-11-17T00:00:00Z",
      "grossTotal": 2464.49,
      "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
      "netTotal": 2071,
      "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "status": "DELIVERED",
      "taxTotal": 393.49,
      "transactionNumber": "LS-2026-0211",
      "transactionType": "DELIVERY_NOTE",
      "updatedAt": "2026-11-17T07:45:00Z",
      "version": 1
    }
  ],
  "nextCursor": "Y3JlYXRlZHwyMDI2LTExLTE3VDA3OjQ1OjAwWnwyZjZiMWQ4NC03YzNlLTRhNWItOWUyMS02YTBjNGQ4YjFlMDM"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/sales/transactions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a transaction of any type (tenant:trade:sales|purchasing|inbound:write by document type)

`POST /api/trade/v1/sales/transactions`

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

`transactionType` is required and must be an active type of the tenant. Without
`transactionNumber` a number with the type's prefix is assigned – an `INVOICE` or `CREDIT_NOTE` without one
is a draft with the placeholder `ENTWURF-<id>` and status `DRAFT` instead, which `issueInvoiceDraft` gives the
next gapless number; `status` defaults to `DRAFT`, `currency` to `EUR`, `documentDate` to today. Totals are computed from `items`; payment terms
default to the partner's terms. `metadata.workflow` is never taken over.

### Request body

`application/json` (required)

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example:

```json
{
  "addressId": "3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10",
  "currency": "EUR",
  "headerText": "Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.",
  "items": [
    {
      "articleNumber": "LNVT14G5",
      "discountPercent": 3,
      "name": "Lenovo ThinkPad T14 Gen 5",
      "positionType": "normal",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 1249
    },
    {
      "isOptional": true,
      "isSelected": false,
      "name": "Docking Station USB-C",
      "positionType": "optional",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 189
    }
  ],
  "recipientAddress": {
    "city": "Berlin",
    "country": "DE",
    "street": "Hauptstraße 12",
    "zip": "10115"
  },
  "recipientCompany": "Muster GmbH",
  "recipientEmail": "einkauf@muster-gmbh.de",
  "recipientName": "Erika Mustermann",
  "transactionType": "OFFER",
  "validUntil": "2026-11-30T00:00:00Z"
}
```

### Responses

- **201** The transaction (`application/json`)
- **400** Invalid body; without `transactionType` code `invalid` with field `transactionType` (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** The tenant has no such transaction type or it is not active (code `type_inactive`) (`application/json`)

Fields of the 201 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-02T09:14:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "documentDate": "2026-11-02T00:00:00Z",
  "exchangeRate": 1,
  "footerText": "Wir freuen uns auf Ihren Auftrag.",
  "grossTotal": 3940.09,
  "headerText": "Vielen Dank für Ihre Anfrage zum WLAN-Ausbau im Gästebereich. Gerne bieten wir Ihnen an:",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
  "items": [
    {
      "articleNumber": "NW-2002",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d01",
      "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "sortOrder": 1,
      "taxRate": 19,
      "totalPriceGross": 1635.06,
      "totalPriceNet": 1374,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 229
    },
    {
      "articleNumber": "NW-2001",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d02",
      "name": "Switch 24 Port Gigabit PoE+, managed",
      "positionNumber": 2,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "sortOrder": 2,
      "taxRate": 19,
      "totalPriceGross": 712.81,
      "totalPriceNet": 599,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 599
    },
    {
      "articleNumber": "NW-2003",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d03",
      "name": "Patchkabel Cat.6a 2 m, grau",
      "positionNumber": 3,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "quantity": 20,
      "sortOrder": 3,
      "taxRate": 19,
      "totalPriceGross": 116.62,
      "totalPriceNet": 98,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 4.9
    },
    {
      "articleNumber": "DL-9001",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d04",
      "name": "Technikerstunde vor Ort",
      "positionNumber": 4,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c11",
      "quantity": 10,
      "sortOrder": 4,
      "taxRate": 19,
      "totalPriceGross": 1368.5,
      "totalPriceNet": 1150,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STD",
      "unitPriceNet": 115
    },
    {
      "articleNumber": "DL-9004",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d05",
      "name": "Anfahrtspauschale Zone 1",
      "positionNumber": 5,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c14",
      "quantity": 2,
      "sortOrder": 5,
      "taxRate": 19,
      "totalPriceGross": 107.1,
      "totalPriceNet": 90,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "PAU",
      "unitPriceNet": 45
    }
  ],
  "netDays": 30,
  "netTotal": 3311,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "paymentTermCode": "14T2",
  "paymentTermsText": "14 Tage 2 % Skonto, 30 Tage netto",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientEmail": "katrin.stadler@alpenhotel-seeblick.example",
  "recipientName": "Katrin Stadler",
  "skontoDays1": 14,
  "skontoRate1": 2,
  "sourceKind": "MANUAL",
  "status": "SENT",
  "taxTotal": 629.09,
  "tenantName": "DEMO",
  "transactionNumber": "AN-2026-0187",
  "transactionType": "OFFER",
  "updatedAt": "2026-11-02T09:31:00Z",
  "validUntil": "2026-12-02T00:00:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/transactions' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10","currency":"EUR","headerText":"Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.","items":[{"articleNumber":"LNVT14G5","discountPercent":3,"name":"Lenovo ThinkPad T14 Gen 5","positionType":"normal","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":1249},{"isOptional":true,"isSelected":false,"name":"Docking Station USB-C","positionType":"optional","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":189}],"recipientAddress":{"city":"Berlin","country":"DE","street":"Hauptstraße 12","zip":"10115"},"recipientCompany":"Muster GmbH","recipientEmail":"einkauf@muster-gmbh.de","recipientName":"Erika Mustermann","transactionType":"OFFER","validUntil":"2026-11-30T00:00:00Z"}'
```

## Get a transaction with its lines (tenant:trade:sales|purchasing|inbound:read by document type)

`GET /api/trade/v1/sales/transactions/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The transaction (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-02T09:14:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "documentDate": "2026-11-02T00:00:00Z",
  "exchangeRate": 1,
  "footerText": "Wir freuen uns auf Ihren Auftrag.",
  "grossTotal": 3940.09,
  "headerText": "Vielen Dank für Ihre Anfrage zum WLAN-Ausbau im Gästebereich. Gerne bieten wir Ihnen an:",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
  "items": [
    {
      "articleNumber": "NW-2002",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d01",
      "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "sortOrder": 1,
      "taxRate": 19,
      "totalPriceGross": 1635.06,
      "totalPriceNet": 1374,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 229
    },
    {
      "articleNumber": "NW-2001",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d02",
      "name": "Switch 24 Port Gigabit PoE+, managed",
      "positionNumber": 2,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "sortOrder": 2,
      "taxRate": 19,
      "totalPriceGross": 712.81,
      "totalPriceNet": 599,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 599
    },
    {
      "articleNumber": "NW-2003",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d03",
      "name": "Patchkabel Cat.6a 2 m, grau",
      "positionNumber": 3,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "quantity": 20,
      "sortOrder": 3,
      "taxRate": 19,
      "totalPriceGross": 116.62,
      "totalPriceNet": 98,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 4.9
    },
    {
      "articleNumber": "DL-9001",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d04",
      "name": "Technikerstunde vor Ort",
      "positionNumber": 4,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c11",
      "quantity": 10,
      "sortOrder": 4,
      "taxRate": 19,
      "totalPriceGross": 1368.5,
      "totalPriceNet": 1150,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STD",
      "unitPriceNet": 115
    },
    {
      "articleNumber": "DL-9004",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d05",
      "name": "Anfahrtspauschale Zone 1",
      "positionNumber": 5,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c14",
      "quantity": 2,
      "sortOrder": 5,
      "taxRate": 19,
      "totalPriceGross": 107.1,
      "totalPriceNet": 90,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "PAU",
      "unitPriceNet": 45
    }
  ],
  "netDays": 30,
  "netTotal": 3311,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "paymentTermCode": "14T2",
  "paymentTermsText": "14 Tage 2 % Skonto, 30 Tage netto",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientEmail": "katrin.stadler@alpenhotel-seeblick.example",
  "recipientName": "Katrin Stadler",
  "skontoDays1": 14,
  "skontoRate1": 2,
  "sourceKind": "MANUAL",
  "status": "SENT",
  "taxTotal": 629.09,
  "tenantName": "DEMO",
  "transactionNumber": "AN-2026-0187",
  "transactionType": "OFFER",
  "updatedAt": "2026-11-02T09:31:00Z",
  "validUntil": "2026-12-02T00:00:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/sales/transactions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Replace a transaction (tenant:trade:sales|purchasing|inbound:write by document type)

`PUT /api/trade/v1/sales/transactions/{id}`

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

Replaces the header with the body (send the complete document). `items`, when present, replace
all lines; totals are recomputed from the lines in the body, so send `items` with every update.
Kept regardless of the body: `metadata.workflow`, `type_data.acceptance`, an existing
`frozenSnapshot` and the number of inbound invoices. `externalTransactionNumber` is only written
for purchase orders. A delivery note made from an order changes only in its header; its status, number, order link,
totals and lines stay (409 for a new status or `items`). A draft invoice made from delivery notes or an order
(placeholder number `ENTWURF-<id>`) keeps its number, status, order link and `typeData.sources`; a line linked to an
order line may shrink but not grow (409); a line named twice or a negative quantity is 422. A draft credit note keeps
the same and its `typeData.correctedInvoice` and `returnToStock`. An issued invoice or credit note (status `ISSUED`)
is never changed (409 `issued_document`), and status `ISSUED` is set only by `issueInvoiceDraft` (409 `issue_only`,
also for a create).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example:

```json
{
  "addressId": "3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10",
  "currency": "EUR",
  "headerText": "Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.",
  "items": [
    {
      "articleNumber": "LNVT14G5",
      "discountPercent": 3,
      "name": "Lenovo ThinkPad T14 Gen 5",
      "positionType": "normal",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 1249
    },
    {
      "isOptional": true,
      "isSelected": false,
      "name": "Docking Station USB-C",
      "positionType": "optional",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 189
    }
  ],
  "recipientAddress": {
    "city": "Berlin",
    "country": "DE",
    "street": "Hauptstraße 12",
    "zip": "10115"
  },
  "recipientCompany": "Muster GmbH",
  "recipientEmail": "einkauf@muster-gmbh.de",
  "recipientName": "Erika Mustermann",
  "transactionType": "OFFER",
  "validUntil": "2026-11-30T00:00:00Z"
}
```

### Responses

- **200** The transaction (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** A delivery note made from an order: status, type and lines are fixed (cancel it with `cancelSalesDeliveryNote`). A line of a draft invoice would invoice more than it reserved. An issued invoice or credit note (`code` `issued_document`), or status `ISSUED` in the body (`code` `issue_only`). (`application/json`)
- **422** A line of a draft invoice is named twice or has a negative quantity. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-02T09:14:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "documentDate": "2026-11-02T00:00:00Z",
  "exchangeRate": 1,
  "footerText": "Wir freuen uns auf Ihren Auftrag.",
  "grossTotal": 3940.09,
  "headerText": "Vielen Dank für Ihre Anfrage zum WLAN-Ausbau im Gästebereich. Gerne bieten wir Ihnen an:",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
  "items": [
    {
      "articleNumber": "NW-2002",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d01",
      "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "sortOrder": 1,
      "taxRate": 19,
      "totalPriceGross": 1635.06,
      "totalPriceNet": 1374,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 229
    },
    {
      "articleNumber": "NW-2001",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d02",
      "name": "Switch 24 Port Gigabit PoE+, managed",
      "positionNumber": 2,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "sortOrder": 2,
      "taxRate": 19,
      "totalPriceGross": 712.81,
      "totalPriceNet": 599,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 599
    },
    {
      "articleNumber": "NW-2003",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d03",
      "name": "Patchkabel Cat.6a 2 m, grau",
      "positionNumber": 3,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "quantity": 20,
      "sortOrder": 3,
      "taxRate": 19,
      "totalPriceGross": 116.62,
      "totalPriceNet": 98,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 4.9
    },
    {
      "articleNumber": "DL-9001",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d04",
      "name": "Technikerstunde vor Ort",
      "positionNumber": 4,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c11",
      "quantity": 10,
      "sortOrder": 4,
      "taxRate": 19,
      "totalPriceGross": 1368.5,
      "totalPriceNet": 1150,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STD",
      "unitPriceNet": 115
    },
    {
      "articleNumber": "DL-9004",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d05",
      "name": "Anfahrtspauschale Zone 1",
      "positionNumber": 5,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c14",
      "quantity": 2,
      "sortOrder": 5,
      "taxRate": 19,
      "totalPriceGross": 107.1,
      "totalPriceNet": 90,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "PAU",
      "unitPriceNet": 45
    }
  ],
  "netDays": 30,
  "netTotal": 3311,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "paymentTermCode": "14T2",
  "paymentTermsText": "14 Tage 2 % Skonto, 30 Tage netto",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientEmail": "katrin.stadler@alpenhotel-seeblick.example",
  "recipientName": "Katrin Stadler",
  "skontoDays1": 14,
  "skontoRate1": 2,
  "sourceKind": "MANUAL",
  "status": "SENT",
  "taxTotal": 629.09,
  "tenantName": "DEMO",
  "transactionNumber": "AN-2026-0187",
  "transactionType": "OFFER",
  "updatedAt": "2026-11-02T09:31:00Z",
  "validUntil": "2026-12-02T00:00:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/sales/transactions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10","currency":"EUR","headerText":"Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.","items":[{"articleNumber":"LNVT14G5","discountPercent":3,"name":"Lenovo ThinkPad T14 Gen 5","positionType":"normal","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":1249},{"isOptional":true,"isSelected":false,"name":"Docking Station USB-C","positionType":"optional","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":189}],"recipientAddress":{"city":"Berlin","country":"DE","street":"Hauptstraße 12","zip":"10115"},"recipientCompany":"Muster GmbH","recipientEmail":"einkauf@muster-gmbh.de","recipientName":"Erika Mustermann","transactionType":"OFFER","validUntil":"2026-11-30T00:00:00Z"}'
```

## Delete a transaction (tenant:trade:sales|purchasing|inbound:write by document type)

`DELETE /api/trade/v1/sales/transactions/{id}`

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

The deletion is recorded in the protocol, which stays readable. A delivery note made from an order is cancelled (`cancelSalesDeliveryNote`), not deleted (409). An order (revision) whose lines delivery notes, invoices or credit notes refer to is not deleted (409). An interim invoice a final invoice deducts cannot be deleted (`409 invoice_deducted`); deleting the final draft frees it.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Deleted (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** A delivery note made from an order (cancel it instead), an order that delivery notes or invoices refer to, or an issued invoice or credit note (`code` `issued_document`; correct it with a credit note), or an interim invoice a final invoice deducts (`code` `invoice_deducted`). (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `status` (string, required): Outcome of the request.

Example 200 answer:

```json
{
  "status": "deleted"
}
```

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/trade/v1/sales/transactions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create the next version of a transaction (tenant:trade:sales|purchasing|inbound:write by document type)

`POST /api/trade/v1/sales/transactions/{id}/revision`

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

Copies the document and its lines as version `n+1` in status `DRAFT` with `predecessorId` set; the frozen snapshot and an offer acceptance are not copied. No request body.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **201** The transaction (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** A delivery note made from an order or an issued invoice or credit note (`code` `issued_document`) has no revisions; a draft another module made (`numberPending`) is changed or released, not revised. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 201 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-05T13:40:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "documentDate": "2026-11-02T00:00:00Z",
  "exchangeRate": 1,
  "footerText": "Wir freuen uns auf Ihren Auftrag.",
  "grossTotal": 3940.09,
  "headerText": "Vielen Dank für Ihre Anfrage zum WLAN-Ausbau im Gästebereich. Gerne bieten wir Ihnen an:",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e07",
  "items": [
    {
      "articleNumber": "NW-2002",
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d11",
      "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "positionNumber": 1,
      "positionType": "normal",
      "predecessorLineId": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d01",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "sortOrder": 1,
      "taxRate": 19,
      "totalPriceGross": 1635.06,
      "totalPriceNet": 1374,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e07",
      "unit": "STK",
      "unitPriceNet": 229
    },
    {
      "articleNumber": "NW-2001",
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d12",
      "name": "Switch 24 Port Gigabit PoE+, managed",
      "positionNumber": 2,
      "positionType": "normal",
      "predecessorLineId": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d02",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "sortOrder": 2,
      "taxRate": 19,
      "totalPriceGross": 712.81,
      "totalPriceNet": 599,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e07",
      "unit": "STK",
      "unitPriceNet": 599
    },
    {
      "articleNumber": "NW-2003",
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d13",
      "name": "Patchkabel Cat.6a 2 m, grau",
      "positionNumber": 3,
      "positionType": "normal",
      "predecessorLineId": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d03",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "quantity": 20,
      "sortOrder": 3,
      "taxRate": 19,
      "totalPriceGross": 116.62,
      "totalPriceNet": 98,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e07",
      "unit": "STK",
      "unitPriceNet": 4.9
    },
    {
      "articleNumber": "DL-9001",
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d14",
      "name": "Technikerstunde vor Ort",
      "positionNumber": 4,
      "positionType": "normal",
      "predecessorLineId": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d04",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c11",
      "quantity": 10,
      "sortOrder": 4,
      "taxRate": 19,
      "totalPriceGross": 1368.5,
      "totalPriceNet": 1150,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e07",
      "unit": "STD",
      "unitPriceNet": 115
    },
    {
      "articleNumber": "DL-9004",
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d15",
      "name": "Anfahrtspauschale Zone 1",
      "positionNumber": 5,
      "positionType": "normal",
      "predecessorLineId": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d05",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c14",
      "quantity": 2,
      "sortOrder": 5,
      "taxRate": 19,
      "totalPriceGross": 107.1,
      "totalPriceNet": 90,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e07",
      "unit": "PAU",
      "unitPriceNet": 45
    }
  ],
  "netDays": 30,
  "netTotal": 3311,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "paymentTermCode": "14T2",
  "paymentTermsText": "14 Tage 2 % Skonto, 30 Tage netto",
  "predecessorId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientEmail": "katrin.stadler@alpenhotel-seeblick.example",
  "recipientName": "Katrin Stadler",
  "skontoDays1": 14,
  "skontoRate1": 2,
  "sourceKind": "MANUAL",
  "status": "DRAFT",
  "taxTotal": 629.09,
  "tenantName": "DEMO",
  "transactionNumber": "AN-2026-0187",
  "transactionType": "OFFER",
  "updatedAt": "2026-11-05T13:40:00Z",
  "validUntil": "2026-12-02T00:00:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/transactions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/revision' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Release a reviewed draft invoice or credit note (tenant:trade:invoice:issue)

`POST /api/trade/v1/sales/transactions/{id}/release`

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

Issues a `DRAFT` invoice or credit note: it becomes `SENT`. A draft another module made
(`numberPending: true`, e.g. a project invoice of desk) now takes the next gapless number of the
tenant (`RE-2026-00001`), is dated today (Europe/Berlin) and gets its due date from its net days, so a
discarded draft never leaves a gap. A final invoice is released only while the interim invoices it
deducts are released and not revoked. Writes the protocol entry `RELEASED` and the event
`trade.invoice.released`. No request body.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The transaction (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** `not_releasable`: not a draft invoice or credit note; `deduction_not_released`: a deducted interim invoice is no longer released. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "createdAt": "2026-11-03T06:00:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "documentDate": "2026-11-19T00:00:00Z",
  "dueDate": "2026-12-03T00:00:00Z",
  "exchangeRate": 1,
  "grossTotal": 568.82,
  "headerText": "Fernwartung und Vor-Ort-Einsätze Oktober 2026",
  "id": "5b8c9d0e-1f2a-4b3c-8d4e-6f7a8b9c0d01",
  "items": [
    {
      "articleNumber": "DL-9002",
      "id": "3a6b7c8d-9e0f-4a1b-8c2d-5e6f7a8b9c01",
      "name": "Fernwartung je angefangene 15 Minuten",
      "positionNumber": 1,
      "positionType": "normal",
      "quantity": 7,
      "sortOrder": 1,
      "taxRate": 19,
      "totalPriceGross": 241.57,
      "totalPriceNet": 203,
      "transactionId": "5b8c9d0e-1f2a-4b3c-8d4e-6f7a8b9c0d01",
      "unit": "STK",
      "unitPriceNet": 29
    },
    {
      "articleNumber": "DL-9001",
      "id": "3a6b7c8d-9e0f-4a1b-8c2d-5e6f7a8b9c02",
      "name": "Technikerstunde vor Ort",
      "positionNumber": 2,
      "positionType": "normal",
      "quantity": 2,
      "sortOrder": 2,
      "taxRate": 19,
      "totalPriceGross": 273.7,
      "totalPriceNet": 230,
      "transactionId": "5b8c9d0e-1f2a-4b3c-8d4e-6f7a8b9c0d01",
      "unit": "STD",
      "unitPriceNet": 115
    },
    {
      "articleNumber": "DL-9004",
      "id": "3a6b7c8d-9e0f-4a1b-8c2d-5e6f7a8b9c03",
      "name": "Anfahrtspauschale Zone 1",
      "positionNumber": 3,
      "positionType": "normal",
      "quantity": 1,
      "sortOrder": 3,
      "taxRate": 19,
      "totalPriceGross": 53.55,
      "totalPriceNet": 45,
      "transactionId": "5b8c9d0e-1f2a-4b3c-8d4e-6f7a8b9c0d01",
      "unit": "PAU",
      "unitPriceNet": 45
    }
  ],
  "netDays": 14,
  "netTotal": 478,
  "numberPending": false,
  "paymentTermCode": "14N",
  "paymentTermsText": "14 Tage netto",
  "recipientAddress": {
    "city": "Regensburg",
    "country": "DE",
    "street": "Maximilianstraße 21",
    "zip": "93047"
  },
  "recipientCompany": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "recipientEmail": "f.pichler@hofmann-partner.example",
  "recipientName": "Florian Pichler",
  "sourceKind": "EXTERNAL",
  "status": "SENT",
  "taxTotal": 90.82,
  "tenantName": "DEMO",
  "transactionNumber": "RE-2026-0399",
  "transactionType": "INVOICE",
  "typeData": {
    "externalReference": "desk:billing-run:2026-10:10002"
  },
  "updatedAt": "2026-11-19T08:40:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/transactions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/release' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the protocol of a transaction (tenant:trade:sales|purchasing|inbound:read by document type)

`GET /api/trade/v1/sales/transactions/{id}/protocol`

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

Oldest first, for documents of any type, also deleted ones. An unknown id answers an empty list.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Protocol entries (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of ProtocolEntry, required)
  - `action` (string): New actions may be added. (one of `CREATED`, `CONVERTED`, `REVISION_CREATED`, `UPDATED`, `STATUS_CHANGED`, `LINES_CHANGED`, `DELETED`, `WORKFLOW_STATUS`, `WORKFLOW_CHANGES`, `RECEIVED`, `REPROCESSED`)
  - `actor` (object): Who made the change.
    - `kind` (string): `user`, `service`, `system`, `workflow` or `public`. (one of `user`, `service`, `system`, `workflow`, `public`)
    - `name` (string): Display name of the actor.
    - `ref` (string): Lower-case e-mail of a person, instance id of a workflow.
  - `changes` (array of object): Changed fields and lines.
    - `field` (string): Name of the changed field.
    - `from` (any): Value before.
    - `lineId` (string): Id of the changed line.
    - `op` (string): `added` or `removed` for a line; absent for a changed field. (one of `added`, `removed`)
    - `position` (integer): Position of the changed line.
    - `to` (any): Value after.
  - `createdAt` (string (date-time)): When the change was made.
  - `fromStatus` (string): Status before the change.
  - `id` (string (uuid)): Id of the protocol entry.
  - `note` (string): Comment of the change.
  - `toStatus` (string): Status after the change.
  - `transactionId` (string (uuid)): Id of the transaction.
  - `transactionNumber` (string): Number of the transaction.
  - `transactionType` (string): Type code of the transaction.

Example 200 answer:

```json
{
  "items": [
    {
      "action": "CREATED",
      "actor": {
        "kind": "user",
        "name": "Felix Neumann",
        "ref": "felix.neumann@muster-it.example"
      },
      "createdAt": "2026-11-02T09:14:00Z",
      "id": "4d7e8f9a-0b1c-4d2e-9f3a-6b7c8d9e0f01",
      "toStatus": "DRAFT",
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "transactionNumber": "AN-2026-0187",
      "transactionType": "OFFER"
    },
    {
      "action": "LINES_CHANGED",
      "actor": {
        "kind": "user",
        "name": "Felix Neumann",
        "ref": "felix.neumann@muster-it.example"
      },
      "changes": [
        {
          "field": "quantity",
          "from": 5,
          "lineId": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d01",
          "position": 1,
          "to": 6
        },
        {
          "field": "netTotal",
          "from": 3082,
          "to": 3311
        }
      ],
      "createdAt": "2026-11-02T09:25:00Z",
      "id": "4d7e8f9a-0b1c-4d2e-9f3a-6b7c8d9e0f02",
      "note": "Sechs statt fünf Access Points",
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "transactionNumber": "AN-2026-0187",
      "transactionType": "OFFER"
    },
    {
      "action": "STATUS_CHANGED",
      "actor": {
        "kind": "user",
        "name": "Felix Neumann",
        "ref": "felix.neumann@muster-it.example"
      },
      "createdAt": "2026-11-02T09:31:00Z",
      "fromStatus": "DRAFT",
      "id": "4d7e8f9a-0b1c-4d2e-9f3a-6b7c8d9e0f03",
      "toStatus": "SENT",
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "transactionNumber": "AN-2026-0187",
      "transactionType": "OFFER"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/sales/transactions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/protocol' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List offers (tenant:trade:sales:read)

`GET /api/trade/v1/sales/offers`

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

`listTransactions` with `type=OFFER`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `search` | query | string |  | Substring of the number, the partner's number or the partner name (case-insensitive). |
| `status` | query | string |  | Exact status. |
| `opportunityId` | query | string (uuid) |  | Only offers of this crm opportunity. |
| `limit` | query | integer |  | Page size; at most 500. (default `50`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** A page of transactions, newest first (creation time, then id); `nextCursor` continues it. (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of Transaction, required)
  - `addressId` (string (uuid)): Masterdata address of the partner.
  - `createdAt` (string (date-time), read-only): When the transaction was created.
  - `currency` (string): ISO 4217; EUR when empty.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `deliveryDate` (string (date-time)): Delivery date.
  - `documentDate` (string (date-time)): Today when empty on create.
  - `documentRefId` (string (uuid)): DMS document of the transaction.
  - `dueDate` (string (date-time)): Due date.
  - `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
  - `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
  - `exchangeRate` (number): 1 when empty.
  - `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
  - `footerText` (string): Text printed below the lines.
  - `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
  - `grossTotal` (number, read-only): Gross total, computed from the lines.
  - `headerText` (string): Text printed above the lines.
  - `id` (string (uuid), read-only): Id of the transaction.
  - `items` (array of TransactionLine): Lines; on update they replace all lines when present.
    - `name` (string, required): Name of the article or line.
    - `quantity` (number, required): Quantity.
    - `articleNumber` (string): Article number in masterdata.
    - `createdAt` (string (date-time), read-only): When the line was created.
    - `description` (string): Description of the line.
    - `discountPercent` (number): Discount in percent.
    - `ean` (string): EAN (GTIN) of the article.
    - `id` (string (uuid), read-only): Id of the line.
    - `isOptional` (boolean): The line is optional (position type `optional`).
    - `isSelected` (boolean): Selected optional lines count in the totals.
    - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
    - `mpn` (string): Manufacturer part number.
    - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
    - `positionNumber` (integer, read-only): Set from the order of `items`.
    - `positionType` (PositionType)
    - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
    - `productId` (string (uuid)): Masterdata article (product) id.
    - `sortOrder` (integer): Sort order (ascending).
    - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
    - `taxRate` (number): Percent.
    - `totalPriceGross` (number, read-only): Gross total of the line, computed.
    - `totalPriceNet` (number, read-only): Net total of the line, computed.
    - `transactionId` (string (uuid), read-only): Id of the transaction.
    - `unit` (string): Unit of measure.
    - `unitPriceNet` (number): Negative for a credit position.
    - `updatedAt` (string (date-time), read-only): When the line was last changed.
  - `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number, read-only): Computed from the lines.
  - `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
  - `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
  - `partnerReference` (string): The partner's order reference (BT-13).
  - `paymentMethodCode` (string): Code of the payment method in masterdata.
  - `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
  - `paymentTermsText` (string): Payment terms as printed text.
  - `predecessorId` (string (uuid)): Previous version of the same document.
  - `recipientAddress` (object): Address snapshot of the partner.
  - `recipientCompany` (string): Company of the recipient.
  - `recipientEmail` (string): E-mail of the recipient.
  - `recipientName` (string): Name of the recipient.
  - `skontoDays1` (integer): Days of the first cash discount.
  - `skontoDays2` (integer): Days of the second cash discount.
  - `skontoRate1` (number): Rate in percent of the first cash discount.
  - `skontoRate2` (number): Rate in percent of the second cash discount.
  - `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
  - `sourceTransactionId` (string (uuid)): Document this one was made from.
  - `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
  - `taxTotal` (number, read-only): Tax total, computed from the lines.
  - `tenantName` (string, read-only): Name of the tenant.
  - `transactionNumber` (string): Assigned with the type's prefix when empty on create.
  - `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
  - `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
  - `updatedAt` (string (date-time), read-only): When the transaction was last changed.
  - `validUntil` (string (date-time)): Offers only.
  - `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
      "createdAt": "2026-11-02T09:14:00Z",
      "currency": "EUR",
      "documentDate": "2026-11-02T00:00:00Z",
      "grossTotal": 3940.09,
      "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "netTotal": 3311,
      "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
      "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "status": "SENT",
      "taxTotal": 629.09,
      "transactionNumber": "AN-2026-0187",
      "transactionType": "OFFER",
      "updatedAt": "2026-11-02T09:31:00Z",
      "validUntil": "2026-12-02T00:00:00Z",
      "version": 1
    },
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
      "createdAt": "2026-10-28T11:00:00Z",
      "currency": "EUR",
      "documentDate": "2026-10-28T00:00:00Z",
      "grossTotal": 8986.88,
      "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e08",
      "netTotal": 7552,
      "recipientCompany": "Donau Maschinenbau AG",
      "status": "ACCEPTED",
      "taxTotal": 1434.88,
      "transactionNumber": "AN-2026-0186",
      "transactionType": "OFFER",
      "updatedAt": "2026-11-04T16:22:00Z",
      "validUntil": "2026-11-27T00:00:00Z",
      "version": 1
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/sales/offers' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create an offer (tenant:trade:sales:write)

`POST /api/trade/v1/sales/offers`

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

`createTransaction` with `transactionType` set to `OFFER`. `validUntil` is stored with the offer. `opportunityId` links the offer to a crm opportunity (400 `invalid` with `field` `opportunityId` when it is no UUID).

### Request body

`application/json` (required)

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example:

```json
{
  "addressId": "3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10",
  "currency": "EUR",
  "headerText": "Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.",
  "items": [
    {
      "articleNumber": "LNVT14G5",
      "discountPercent": 3,
      "name": "Lenovo ThinkPad T14 Gen 5",
      "positionType": "normal",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 1249
    },
    {
      "isOptional": true,
      "isSelected": false,
      "name": "Docking Station USB-C",
      "positionType": "optional",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 189
    }
  ],
  "recipientAddress": {
    "city": "Berlin",
    "country": "DE",
    "street": "Hauptstraße 12",
    "zip": "10115"
  },
  "recipientCompany": "Muster GmbH",
  "recipientEmail": "einkauf@muster-gmbh.de",
  "recipientName": "Erika Mustermann",
  "transactionType": "OFFER",
  "validUntil": "2026-11-30T00:00:00Z"
}
```

### Responses

- **201** The transaction (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 201 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-02T09:14:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "documentDate": "2026-11-02T00:00:00Z",
  "exchangeRate": 1,
  "footerText": "Wir freuen uns auf Ihren Auftrag.",
  "grossTotal": 3940.09,
  "headerText": "Vielen Dank für Ihre Anfrage zum WLAN-Ausbau im Gästebereich. Gerne bieten wir Ihnen an:",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
  "items": [
    {
      "articleNumber": "NW-2002",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d01",
      "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "sortOrder": 1,
      "taxRate": 19,
      "totalPriceGross": 1635.06,
      "totalPriceNet": 1374,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 229
    },
    {
      "articleNumber": "NW-2001",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d02",
      "name": "Switch 24 Port Gigabit PoE+, managed",
      "positionNumber": 2,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "sortOrder": 2,
      "taxRate": 19,
      "totalPriceGross": 712.81,
      "totalPriceNet": 599,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 599
    },
    {
      "articleNumber": "NW-2003",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d03",
      "name": "Patchkabel Cat.6a 2 m, grau",
      "positionNumber": 3,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "quantity": 20,
      "sortOrder": 3,
      "taxRate": 19,
      "totalPriceGross": 116.62,
      "totalPriceNet": 98,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STK",
      "unitPriceNet": 4.9
    },
    {
      "articleNumber": "DL-9001",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d04",
      "name": "Technikerstunde vor Ort",
      "positionNumber": 4,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c11",
      "quantity": 10,
      "sortOrder": 4,
      "taxRate": 19,
      "totalPriceGross": 1368.5,
      "totalPriceNet": 1150,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "STD",
      "unitPriceNet": 115
    },
    {
      "articleNumber": "DL-9004",
      "discountPercent": 0,
      "id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d05",
      "name": "Anfahrtspauschale Zone 1",
      "positionNumber": 5,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c14",
      "quantity": 2,
      "sortOrder": 5,
      "taxRate": 19,
      "totalPriceGross": 107.1,
      "totalPriceNet": 90,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "unit": "PAU",
      "unitPriceNet": 45
    }
  ],
  "netDays": 30,
  "netTotal": 3311,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "paymentTermCode": "14T2",
  "paymentTermsText": "14 Tage 2 % Skonto, 30 Tage netto",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientEmail": "katrin.stadler@alpenhotel-seeblick.example",
  "recipientName": "Katrin Stadler",
  "skontoDays1": 14,
  "skontoRate1": 2,
  "sourceKind": "MANUAL",
  "status": "SENT",
  "taxTotal": 629.09,
  "tenantName": "DEMO",
  "transactionNumber": "AN-2026-0187",
  "transactionType": "OFFER",
  "updatedAt": "2026-11-02T09:31:00Z",
  "validUntil": "2026-12-02T00:00:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/offers' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10","currency":"EUR","headerText":"Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.","items":[{"articleNumber":"LNVT14G5","discountPercent":3,"name":"Lenovo ThinkPad T14 Gen 5","positionType":"normal","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":1249},{"isOptional":true,"isSelected":false,"name":"Docking Station USB-C","positionType":"optional","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":189}],"recipientAddress":{"city":"Berlin","country":"DE","street":"Hauptstraße 12","zip":"10115"},"recipientCompany":"Muster GmbH","recipientEmail":"einkauf@muster-gmbh.de","recipientName":"Erika Mustermann","transactionType":"OFFER","validUntil":"2026-11-30T00:00:00Z"}'
```

## List order confirmations (tenant:trade:sales:read)

`GET /api/trade/v1/sales/order-confirmations`

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

`listTransactions` with `type=ORDER`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `search` | query | string |  | Substring of the number, the partner's number or the partner name (case-insensitive). |
| `status` | query | string |  | Exact status. |
| `limit` | query | integer |  | Page size; at most 500. (default `50`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** A page of transactions, newest first (creation time, then id); `nextCursor` continues it. (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of Transaction, required)
  - `addressId` (string (uuid)): Masterdata address of the partner.
  - `createdAt` (string (date-time), read-only): When the transaction was created.
  - `currency` (string): ISO 4217; EUR when empty.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `deliveryDate` (string (date-time)): Delivery date.
  - `documentDate` (string (date-time)): Today when empty on create.
  - `documentRefId` (string (uuid)): DMS document of the transaction.
  - `dueDate` (string (date-time)): Due date.
  - `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
  - `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
  - `exchangeRate` (number): 1 when empty.
  - `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
  - `footerText` (string): Text printed below the lines.
  - `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
  - `grossTotal` (number, read-only): Gross total, computed from the lines.
  - `headerText` (string): Text printed above the lines.
  - `id` (string (uuid), read-only): Id of the transaction.
  - `items` (array of TransactionLine): Lines; on update they replace all lines when present.
    - `name` (string, required): Name of the article or line.
    - `quantity` (number, required): Quantity.
    - `articleNumber` (string): Article number in masterdata.
    - `createdAt` (string (date-time), read-only): When the line was created.
    - `description` (string): Description of the line.
    - `discountPercent` (number): Discount in percent.
    - `ean` (string): EAN (GTIN) of the article.
    - `id` (string (uuid), read-only): Id of the line.
    - `isOptional` (boolean): The line is optional (position type `optional`).
    - `isSelected` (boolean): Selected optional lines count in the totals.
    - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
    - `mpn` (string): Manufacturer part number.
    - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
    - `positionNumber` (integer, read-only): Set from the order of `items`.
    - `positionType` (PositionType)
    - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
    - `productId` (string (uuid)): Masterdata article (product) id.
    - `sortOrder` (integer): Sort order (ascending).
    - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
    - `taxRate` (number): Percent.
    - `totalPriceGross` (number, read-only): Gross total of the line, computed.
    - `totalPriceNet` (number, read-only): Net total of the line, computed.
    - `transactionId` (string (uuid), read-only): Id of the transaction.
    - `unit` (string): Unit of measure.
    - `unitPriceNet` (number): Negative for a credit position.
    - `updatedAt` (string (date-time), read-only): When the line was last changed.
  - `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number, read-only): Computed from the lines.
  - `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
  - `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
  - `partnerReference` (string): The partner's order reference (BT-13).
  - `paymentMethodCode` (string): Code of the payment method in masterdata.
  - `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
  - `paymentTermsText` (string): Payment terms as printed text.
  - `predecessorId` (string (uuid)): Previous version of the same document.
  - `recipientAddress` (object): Address snapshot of the partner.
  - `recipientCompany` (string): Company of the recipient.
  - `recipientEmail` (string): E-mail of the recipient.
  - `recipientName` (string): Name of the recipient.
  - `skontoDays1` (integer): Days of the first cash discount.
  - `skontoDays2` (integer): Days of the second cash discount.
  - `skontoRate1` (number): Rate in percent of the first cash discount.
  - `skontoRate2` (number): Rate in percent of the second cash discount.
  - `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
  - `sourceTransactionId` (string (uuid)): Document this one was made from.
  - `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
  - `taxTotal` (number, read-only): Tax total, computed from the lines.
  - `tenantName` (string, read-only): Name of the tenant.
  - `transactionNumber` (string): Assigned with the type's prefix when empty on create.
  - `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
  - `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
  - `updatedAt` (string (date-time), read-only): When the transaction was last changed.
  - `validUntil` (string (date-time)): Offers only.
  - `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
      "createdAt": "2026-11-06T10:02:00Z",
      "currency": "EUR",
      "deliveryDate": "2026-11-24T00:00:00Z",
      "documentDate": "2026-11-06T00:00:00Z",
      "grossTotal": 3940.09,
      "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "netTotal": 3311,
      "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
      "status": "CONFIRMED",
      "taxTotal": 629.09,
      "transactionNumber": "AB-2026-0143",
      "transactionType": "ORDER",
      "updatedAt": "2026-11-06T10:02:00Z",
      "version": 1
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/sales/order-confirmations' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create an order confirmation (tenant:trade:sales:write)

`POST /api/trade/v1/sales/order-confirmations`

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

`createTransaction` with `transactionType` set to `ORDER`.

### Request body

`application/json` (required)

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example:

```json
{
  "addressId": "3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10",
  "currency": "EUR",
  "headerText": "Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.",
  "items": [
    {
      "articleNumber": "LNVT14G5",
      "discountPercent": 3,
      "name": "Lenovo ThinkPad T14 Gen 5",
      "positionType": "normal",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 1249
    },
    {
      "isOptional": true,
      "isSelected": false,
      "name": "Docking Station USB-C",
      "positionType": "optional",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 189
    }
  ],
  "recipientAddress": {
    "city": "Berlin",
    "country": "DE",
    "street": "Hauptstraße 12",
    "zip": "10115"
  },
  "recipientCompany": "Muster GmbH",
  "recipientEmail": "einkauf@muster-gmbh.de",
  "recipientName": "Erika Mustermann",
  "transactionType": "OFFER",
  "validUntil": "2026-11-30T00:00:00Z"
}
```

### Responses

- **201** The transaction (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 201 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-06T10:02:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-11-24T00:00:00Z",
  "documentDate": "2026-11-06T00:00:00Z",
  "exchangeRate": 1,
  "grossTotal": 3940.09,
  "headerText": "Vielen Dank für Ihren Auftrag. Wir bestätigen Ihnen die folgenden Positionen.",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
  "items": [
    {
      "articleNumber": "NW-2002",
      "id": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "sortOrder": 1,
      "taxRate": 19,
      "totalPriceGross": 1635.06,
      "totalPriceNet": 1374,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "unit": "STK",
      "unitPriceNet": 229
    },
    {
      "articleNumber": "NW-2001",
      "id": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e02",
      "name": "Switch 24 Port Gigabit PoE+, managed",
      "positionNumber": 2,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "sortOrder": 2,
      "taxRate": 19,
      "totalPriceGross": 712.81,
      "totalPriceNet": 599,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "unit": "STK",
      "unitPriceNet": 599
    },
    {
      "articleNumber": "NW-2003",
      "id": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e03",
      "name": "Patchkabel Cat.6a 2 m, grau",
      "positionNumber": 3,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "quantity": 20,
      "sortOrder": 3,
      "taxRate": 19,
      "totalPriceGross": 116.62,
      "totalPriceNet": 98,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "unit": "STK",
      "unitPriceNet": 4.9
    },
    {
      "articleNumber": "DL-9001",
      "id": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e04",
      "name": "Technikerstunde vor Ort",
      "positionNumber": 4,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c11",
      "quantity": 10,
      "sortOrder": 4,
      "taxRate": 19,
      "totalPriceGross": 1368.5,
      "totalPriceNet": 1150,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "unit": "STD",
      "unitPriceNet": 115
    },
    {
      "articleNumber": "DL-9004",
      "id": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e05",
      "name": "Anfahrtspauschale Zone 1",
      "positionNumber": 5,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c14",
      "quantity": 2,
      "sortOrder": 5,
      "taxRate": 19,
      "totalPriceGross": 107.1,
      "totalPriceNet": 90,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "unit": "PAU",
      "unitPriceNet": 45
    }
  ],
  "netDays": 30,
  "netTotal": 3311,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "partnerReference": "Auftrag vom 06.11.2026, K. Stadler",
  "paymentTermCode": "14T2",
  "paymentTermsText": "14 Tage 2 % Skonto, 30 Tage netto",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientEmail": "katrin.stadler@alpenhotel-seeblick.example",
  "recipientName": "Katrin Stadler",
  "skontoDays1": 14,
  "skontoRate1": 2,
  "sourceKind": "MANUAL",
  "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
  "status": "CONFIRMED",
  "taxTotal": 629.09,
  "tenantName": "DEMO",
  "transactionNumber": "AB-2026-0143",
  "transactionType": "ORDER",
  "updatedAt": "2026-11-06T10:02:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/order-confirmations' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10","currency":"EUR","headerText":"Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.","items":[{"articleNumber":"LNVT14G5","discountPercent":3,"name":"Lenovo ThinkPad T14 Gen 5","positionType":"normal","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":1249},{"isOptional":true,"isSelected":false,"name":"Docking Station USB-C","positionType":"optional","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":189}],"recipientAddress":{"city":"Berlin","country":"DE","street":"Hauptstraße 12","zip":"10115"},"recipientCompany":"Muster GmbH","recipientEmail":"einkauf@muster-gmbh.de","recipientName":"Erika Mustermann","transactionType":"OFFER","validUntil":"2026-11-30T00:00:00Z"}'
```

## Get the delivered and invoiced quantities of an order (tenant:trade:sales:read)

`GET /api/trade/v1/sales/order-confirmations/{id}/fulfilment`

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

Ordered, delivered (delivery notes) and invoiced (invoices minus credit notes) quantity per deliverable line
(normal and selected optional lines), computed when read. Cancelled documents and superseded revisions do not
count. Any revision id of the order answers for its newest revision (`orderId`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Fulfilment of the order (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `lines` (array of object): Quantities per order line.
  - `delivered` (number): Quantity on delivery notes (not cancelled).
  - `invoiced` (number): Quantity invoiced.
  - `lineId` (string (uuid)): Id of the order line.
  - `ordered` (number): Quantity ordered.
- `orderId` (string (uuid)): The newest revision of the order.
- `status` (string): `INVOICED` when every line is invoiced in full (also without delivery), `DELIVERED` when every line is delivered in full, `PARTIALLY_DELIVERED` when anything is delivered. (one of `OPEN`, `PARTIALLY_DELIVERED`, `DELIVERED`, `INVOICED`)

Example 200 answer:

```json
{
  "lines": [
    {
      "delivered": 6,
      "invoiced": 6,
      "lineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "ordered": 6
    },
    {
      "delivered": 1,
      "invoiced": 1,
      "lineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e02",
      "ordered": 1
    },
    {
      "delivered": 20,
      "invoiced": 20,
      "lineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e03",
      "ordered": 20
    },
    {
      "delivered": 0,
      "invoiced": 0,
      "lineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e04",
      "ordered": 10
    },
    {
      "delivered": 0,
      "invoiced": 0,
      "lineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e05",
      "ordered": 2
    }
  ],
  "orderId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
  "status": "PARTIALLY_DELIVERED"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/sales/order-confirmations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/fulfilment' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a delivery note from an order (tenant:trade:sales:write)

`POST /api/trade/v1/sales/order-confirmations/{id}/delivery-notes`

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

Creates a `DELIVERY_NOTE` in status `DELIVERED` for the newest revision of the order (any revision id may be
given), numbered gaplessly per tenant and year (`<prefix of the type>-<year>-<nnnnn>`, default `LS`, year of the
delivery date in Europe/Berlin). Partial deliveries are allowed; an empty body or empty `lines` delivers
everything still open. Each line copies article, unit, price and tax rate of its order line and points to it
(`sourceLineId`); the title a line stands under is copied with quantity 0. Partner, address snapshot and the
customer's order reference are taken from the order (`sourceTransactionId`). Deliveries of one order run one
at a time, so a line is never delivered beyond its ordered quantity. The stock of the lines' articles is
booked out in the same transaction (not for drop shipments). Publishes `trade.deliverynote.created`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `deliveryDate` (string (date-time)): Delivery and document date (default: today for both); its year selects the number counter.
- `lines` (array of object): Quantities to deliver; empty or missing delivers everything still open.
  - `orderLineId` (string (uuid), required): Line of the newest revision of the order.
  - `quantity` (number, required): Quantity to deliver.
  - `serialNumbers` (array of string): Stored in `lineData.serialNumbers` and booked with the stock movement.
- `note` (string): Header text of the delivery note.

Example:

```json
{
  "deliveryDate": "2026-11-17T00:00:00Z",
  "lines": [
    {
      "orderLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "quantity": 6,
      "serialNumbers": [
        "AP6-24K0113",
        "AP6-24K0114",
        "AP6-24K0115",
        "AP6-24K0116",
        "AP6-24K0117",
        "AP6-24K0118"
      ]
    },
    {
      "orderLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e02",
      "quantity": 1,
      "serialNumbers": [
        "SW24-9K2207"
      ]
    },
    {
      "orderLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e03",
      "quantity": 20
    }
  ],
  "note": "WLAN-Hardware für den Gästebereich"
}
```

### Responses

- **201** The transaction (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** A line exceeds its open quantity (`lineId`, `open`, `requested`), nothing is left to deliver, the order is not confirmed yet (`DRAFT`), or it is revoked or cancelled. (`application/json`)
- **422** The document is no order, a line id is no deliverable line of the newest revision, or a quantity is negative. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 201 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-17T07:45:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-11-17T00:00:00Z",
  "documentDate": "2026-11-17T00:00:00Z",
  "exchangeRate": 1,
  "grossTotal": 2464.49,
  "headerText": "WLAN-Hardware für den Gästebereich",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
  "items": [
    {
      "articleNumber": "NW-2002",
      "id": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
      "lineData": {
        "serialNumbers": [
          "AP6-24K0113",
          "AP6-24K0114",
          "AP6-24K0115",
          "AP6-24K0116",
          "AP6-24K0117",
          "AP6-24K0118"
        ]
      },
      "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "sortOrder": 1,
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "taxRate": 19,
      "totalPriceGross": 1635.06,
      "totalPriceNet": 1374,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
      "unit": "STK",
      "unitPriceNet": 229
    },
    {
      "articleNumber": "NW-2001",
      "id": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
      "lineData": {
        "serialNumbers": [
          "SW24-9K2207"
        ]
      },
      "name": "Switch 24 Port Gigabit PoE+, managed",
      "positionNumber": 2,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "sortOrder": 2,
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e02",
      "taxRate": 19,
      "totalPriceGross": 712.81,
      "totalPriceNet": 599,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
      "unit": "STK",
      "unitPriceNet": 599
    },
    {
      "articleNumber": "NW-2003",
      "id": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f03",
      "name": "Patchkabel Cat.6a 2 m, grau",
      "positionNumber": 3,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "quantity": 20,
      "sortOrder": 3,
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e03",
      "taxRate": 19,
      "totalPriceGross": 116.62,
      "totalPriceNet": 98,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
      "unit": "STK",
      "unitPriceNet": 4.9
    }
  ],
  "netTotal": 2071,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "partnerReference": "Auftrag vom 06.11.2026, K. Stadler",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientName": "Katrin Stadler",
  "sourceKind": "MANUAL",
  "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
  "status": "DELIVERED",
  "taxTotal": 393.49,
  "tenantName": "DEMO",
  "transactionNumber": "LS-2026-0211",
  "transactionType": "DELIVERY_NOTE",
  "updatedAt": "2026-11-17T07:45:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/order-confirmations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/delivery-notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"deliveryDate":"2026-11-17T00:00:00Z","lines":[{"orderLineId":"9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01","quantity":6,"serialNumbers":["AP6-24K0113","AP6-24K0114","AP6-24K0115","AP6-24K0116","AP6-24K0117","AP6-24K0118"]},{"orderLineId":"9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e02","quantity":1,"serialNumbers":["SW24-9K2207"]},{"orderLineId":"9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e03","quantity":20}],"note":"WLAN-Hardware für den Gästebereich"}'
```

## Draft an invoice from delivery notes or an order (tenant:trade:sales:write)

`POST /api/trade/v1/sales/invoices/drafts`

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

Creates a `DRAFT` invoice with the placeholder number `ENTWURF-<id>` (no number is taken until it is issued with
`issueInvoiceDraft`). `sourceIds` are delivery notes of one customer and currency (a collective invoice) or one
confirmed order (what is ordered and not yet invoiced, e.g. services). Price and discount come from the newest
confirmed order revision, quantity, article, serial numbers and tax rate from the delivery note. A draft counts
as invoiced until it is deleted, so a quantity is never drafted twice.

### Request body

`application/json` (required)

- `sourceIds` (array of string (uuid), required)
- `documentDate` (string (date-time)): Invoice date of the draft; issuing sets the issue day
- `footerText` (string)
- `headerText` (string)
- `servicePeriodEnd` (string (date-time)): BT-74
- `servicePeriodStart` (string (date-time)): BT-73

Example:

```json
{
  "documentDate": "2026-11-18T00:00:00Z",
  "headerText": "Wir berechnen Ihnen die Lieferung vom 17.11.2026:",
  "sourceIds": [
    "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03"
  ]
}
```

### Responses

- **201** The transaction (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** Nothing is left to invoice, a delivery note is invoiced already, or the order is not confirmed, revoked or cancelled (German text). (`application/json`)
- **422** Sources of several customers, currencies or payment terms, a source that is no delivery note of an order and no order, or a service period that ends before it starts (German text). (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 201 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-18T08:20:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-11-17T00:00:00Z",
  "documentDate": "2026-11-18T00:00:00Z",
  "exchangeRate": 1,
  "grossTotal": 2464.49,
  "headerText": "Wir berechnen Ihnen die Lieferung vom 17.11.2026:",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
  "items": [
    {
      "articleNumber": "NW-2002",
      "id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01",
      "lineData": {
        "serialNumbers": [
          "AP6-24K0113",
          "AP6-24K0114",
          "AP6-24K0115",
          "AP6-24K0116",
          "AP6-24K0117",
          "AP6-24K0118"
        ]
      },
      "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "sortOrder": 1,
      "sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
      "taxRate": 19,
      "totalPriceGross": 1635.06,
      "totalPriceNet": 1374,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "unit": "STK",
      "unitPriceNet": 229
    },
    {
      "articleNumber": "NW-2001",
      "id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a02",
      "lineData": {
        "serialNumbers": [
          "SW24-9K2207"
        ]
      },
      "name": "Switch 24 Port Gigabit PoE+, managed",
      "positionNumber": 2,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "sortOrder": 2,
      "sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
      "taxRate": 19,
      "totalPriceGross": 712.81,
      "totalPriceNet": 599,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "unit": "STK",
      "unitPriceNet": 599
    },
    {
      "articleNumber": "NW-2003",
      "id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a03",
      "name": "Patchkabel Cat.6a 2 m, grau",
      "positionNumber": 3,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "quantity": 20,
      "sortOrder": 3,
      "sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f03",
      "taxRate": 19,
      "totalPriceGross": 116.62,
      "totalPriceNet": 98,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "unit": "STK",
      "unitPriceNet": 4.9
    }
  ],
  "netDays": 30,
  "netTotal": 2071,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "partnerReference": "Auftrag vom 06.11.2026, K. Stadler",
  "paymentTermCode": "14T2",
  "paymentTermsText": "14 Tage 2 % Skonto, 30 Tage netto",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientEmail": "buchhaltung@alpenhotel-seeblick.example",
  "recipientName": "Buchhaltung",
  "skontoDays1": 14,
  "skontoRate1": 2,
  "sourceKind": "MANUAL",
  "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
  "status": "DRAFT",
  "taxTotal": 393.49,
  "tenantName": "DEMO",
  "transactionNumber": "ENTWURF-2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
  "transactionType": "INVOICE",
  "typeData": {
    "sources": [
      {
        "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
        "number": "LS-2026-0211",
        "orderNumber": "AB-2026-0143",
        "partnerReference": "Auftrag vom 06.11.2026, K. Stadler",
        "type": "DELIVERY_NOTE"
      }
    ]
  },
  "updatedAt": "2026-11-18T08:20:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/invoices/drafts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"documentDate":"2026-11-18T00:00:00Z","headerText":"Wir berechnen Ihnen die Lieferung vom 17.11.2026:","sourceIds":["2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03"]}'
```

## Draft a credit note of an issued invoice (tenant:trade:sales:write)

`POST /api/trade/v1/sales/invoices/{id}/credit-notes`

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

Creates a `DRAFT` credit note (placeholder number, issued with `issueInvoiceDraft` as `GS-<year>-<nnnnn>`, XRechnung
type 381 naming the invoice) of an `ISSUED` invoice: the given invoice lines and quantities, or without `lines`
whatever is not credited yet. A line is never credited beyond its invoiced quantity minus what other credit notes
(drafts included) credit. With `returnToStock` the articles are booked back into stock when it is issued – only for an
invoice made of delivery notes that booked them out of stock (422 for a drop shipment, an order-direct or a
hand-made invoice).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `footerText` (string)
- `headerText` (string)
- `lines` (array of object)
  - `invoiceLineId` (string (uuid), required)
  - `quantity` (number, required)
- `returnToStock` (boolean): Book the credited articles back into stock when the credit note is issued

Example:

```json
{
  "headerText": "Gutschrift für einen nicht benötigten Access Point (Rücknahme).",
  "lines": [
    {
      "invoiceLineId": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01",
      "quantity": 1
    }
  ],
  "returnToStock": true
}
```

### Responses

- **201** The transaction (`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 invoice is not issued, a line would be credited beyond its invoiced quantity, or everything is credited already (German text). (`application/json`)
- **422** A line is no line of the invoice, is named twice or has a negative quantity; or `returnToStock` for goods that never left stock (German text). (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 201 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-19T10:12:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "documentDate": "2026-11-19T00:00:00Z",
  "exchangeRate": 1,
  "grossTotal": 272.51,
  "headerText": "Gutschrift für einen nicht benötigten Access Point (Rücknahme).",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
  "items": [
    {
      "articleNumber": "NW-2002",
      "id": "2f5a6b7c-8d9e-4f0a-9b1c-4d5e6f7a8b01",
      "lineData": {
        "serialNumbers": [
          "AP6-24K0118"
        ]
      },
      "name": "WLAN Access Point Wi-Fi 6 – Rücknahme",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 1,
      "sortOrder": 1,
      "sourceLineId": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01",
      "taxRate": 19,
      "totalPriceGross": 272.51,
      "totalPriceNet": 229,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
      "unit": "STK",
      "unitPriceNet": 229
    }
  ],
  "netDays": 0,
  "netTotal": 229,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "paymentTermsText": "Der Betrag wird Ihnen erstattet.",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientEmail": "buchhaltung@alpenhotel-seeblick.example",
  "recipientName": "Buchhaltung",
  "sourceKind": "MANUAL",
  "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
  "status": "DRAFT",
  "taxTotal": 43.51,
  "tenantName": "DEMO",
  "transactionNumber": "ENTWURF-2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
  "transactionType": "CREDIT_NOTE",
  "typeData": {
    "correctedInvoice": {
      "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "number": "RE-2026-0398"
    },
    "returnToStock": true
  },
  "updatedAt": "2026-11-19T10:12:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/credit-notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"headerText":"Gutschrift für einen nicht benötigten Access Point (Rücknahme).","lines":[{"invoiceLineId":"1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01","quantity":1}],"returnToStock":true}'
```

## List delivery notes (tenant:trade:sales:read)

`GET /api/trade/v1/sales/delivery-notes`

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

`listTransactions` with `type=DELIVERY_NOTE`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `search` | query | string |  | Substring of the number, the partner's number or the partner name (case-insensitive). |
| `status` | query | string |  | Exact status. |
| `limit` | query | integer |  | Page size; at most 500. (default `50`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** A page of transactions, newest first (creation time, then id); `nextCursor` continues it. (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of Transaction, required)
  - `addressId` (string (uuid)): Masterdata address of the partner.
  - `createdAt` (string (date-time), read-only): When the transaction was created.
  - `currency` (string): ISO 4217; EUR when empty.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `deliveryDate` (string (date-time)): Delivery date.
  - `documentDate` (string (date-time)): Today when empty on create.
  - `documentRefId` (string (uuid)): DMS document of the transaction.
  - `dueDate` (string (date-time)): Due date.
  - `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
  - `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
  - `exchangeRate` (number): 1 when empty.
  - `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
  - `footerText` (string): Text printed below the lines.
  - `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
  - `grossTotal` (number, read-only): Gross total, computed from the lines.
  - `headerText` (string): Text printed above the lines.
  - `id` (string (uuid), read-only): Id of the transaction.
  - `items` (array of TransactionLine): Lines; on update they replace all lines when present.
    - `name` (string, required): Name of the article or line.
    - `quantity` (number, required): Quantity.
    - `articleNumber` (string): Article number in masterdata.
    - `createdAt` (string (date-time), read-only): When the line was created.
    - `description` (string): Description of the line.
    - `discountPercent` (number): Discount in percent.
    - `ean` (string): EAN (GTIN) of the article.
    - `id` (string (uuid), read-only): Id of the line.
    - `isOptional` (boolean): The line is optional (position type `optional`).
    - `isSelected` (boolean): Selected optional lines count in the totals.
    - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
    - `mpn` (string): Manufacturer part number.
    - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
    - `positionNumber` (integer, read-only): Set from the order of `items`.
    - `positionType` (PositionType)
    - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
    - `productId` (string (uuid)): Masterdata article (product) id.
    - `sortOrder` (integer): Sort order (ascending).
    - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
    - `taxRate` (number): Percent.
    - `totalPriceGross` (number, read-only): Gross total of the line, computed.
    - `totalPriceNet` (number, read-only): Net total of the line, computed.
    - `transactionId` (string (uuid), read-only): Id of the transaction.
    - `unit` (string): Unit of measure.
    - `unitPriceNet` (number): Negative for a credit position.
    - `updatedAt` (string (date-time), read-only): When the line was last changed.
  - `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number, read-only): Computed from the lines.
  - `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
  - `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
  - `partnerReference` (string): The partner's order reference (BT-13).
  - `paymentMethodCode` (string): Code of the payment method in masterdata.
  - `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
  - `paymentTermsText` (string): Payment terms as printed text.
  - `predecessorId` (string (uuid)): Previous version of the same document.
  - `recipientAddress` (object): Address snapshot of the partner.
  - `recipientCompany` (string): Company of the recipient.
  - `recipientEmail` (string): E-mail of the recipient.
  - `recipientName` (string): Name of the recipient.
  - `skontoDays1` (integer): Days of the first cash discount.
  - `skontoDays2` (integer): Days of the second cash discount.
  - `skontoRate1` (number): Rate in percent of the first cash discount.
  - `skontoRate2` (number): Rate in percent of the second cash discount.
  - `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
  - `sourceTransactionId` (string (uuid)): Document this one was made from.
  - `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
  - `taxTotal` (number, read-only): Tax total, computed from the lines.
  - `tenantName` (string, read-only): Name of the tenant.
  - `transactionNumber` (string): Assigned with the type's prefix when empty on create.
  - `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
  - `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
  - `updatedAt` (string (date-time), read-only): When the transaction was last changed.
  - `validUntil` (string (date-time)): Offers only.
  - `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c04",
      "createdAt": "2026-11-19T11:30:00Z",
      "currency": "EUR",
      "documentDate": "2026-11-19T00:00:00Z",
      "grossTotal": 259.42,
      "id": "4c7d8e9f-0a1b-4c2d-9e3f-5a6b7c8d9e01",
      "netTotal": 218,
      "recipientCompany": "Gemeinschaftspraxis Dr. Lindner \u0026 Kollegen",
      "status": "DRAFT",
      "taxTotal": 41.42,
      "transactionNumber": "LS-2026-0212",
      "transactionType": "DELIVERY_NOTE",
      "updatedAt": "2026-11-19T11:30:00Z",
      "version": 1
    },
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
      "createdAt": "2026-11-17T07:45:00Z",
      "currency": "EUR",
      "documentDate": "2026-11-17T00:00:00Z",
      "grossTotal": 2464.49,
      "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
      "netTotal": 2071,
      "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "status": "DELIVERED",
      "taxTotal": 393.49,
      "transactionNumber": "LS-2026-0211",
      "transactionType": "DELIVERY_NOTE",
      "updatedAt": "2026-11-17T07:45:00Z",
      "version": 1
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/sales/delivery-notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a delivery note (tenant:trade:sales:write)

`POST /api/trade/v1/sales/delivery-notes`

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

`createTransaction` with `transactionType` set to `DELIVERY_NOTE`.

### Request body

`application/json` (required)

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example:

```json
{
  "addressId": "3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10",
  "currency": "EUR",
  "headerText": "Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.",
  "items": [
    {
      "articleNumber": "LNVT14G5",
      "discountPercent": 3,
      "name": "Lenovo ThinkPad T14 Gen 5",
      "positionType": "normal",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 1249
    },
    {
      "isOptional": true,
      "isSelected": false,
      "name": "Docking Station USB-C",
      "positionType": "optional",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 189
    }
  ],
  "recipientAddress": {
    "city": "Berlin",
    "country": "DE",
    "street": "Hauptstraße 12",
    "zip": "10115"
  },
  "recipientCompany": "Muster GmbH",
  "recipientEmail": "einkauf@muster-gmbh.de",
  "recipientName": "Erika Mustermann",
  "transactionType": "OFFER",
  "validUntil": "2026-11-30T00:00:00Z"
}
```

### Responses

- **201** The transaction (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 201 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c04",
  "createdAt": "2026-11-19T11:30:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-11-20T00:00:00Z",
  "documentDate": "2026-11-19T00:00:00Z",
  "exchangeRate": 1,
  "grossTotal": 259.42,
  "headerText": "Ersatz für zwei defekte Headsets am Empfang",
  "id": "4c7d8e9f-0a1b-4c2d-9e3f-5a6b7c8d9e01",
  "items": [
    {
      "articleNumber": "HW-1007",
      "id": "5e8f9a0b-1c2d-4e3f-8a4b-6c7d8e9f0a01",
      "name": "Headset USB Stereo mit Geräuschunterdrückung",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c07",
      "quantity": 2,
      "sortOrder": 1,
      "taxRate": 19,
      "totalPriceGross": 259.42,
      "totalPriceNet": 218,
      "transactionId": "4c7d8e9f-0a1b-4c2d-9e3f-5a6b7c8d9e01",
      "unit": "STK",
      "unitPriceNet": 109
    }
  ],
  "netTotal": 218,
  "recipientAddress": {
    "city": "Landshut",
    "country": "DE",
    "street": "Bahnhofstraße 8",
    "zip": "84028"
  },
  "recipientCompany": "Gemeinschaftspraxis Dr. Lindner \u0026 Kollegen",
  "recipientName": "Petra Kraus",
  "sourceKind": "MANUAL",
  "status": "DRAFT",
  "taxTotal": 41.42,
  "tenantName": "DEMO",
  "transactionNumber": "LS-2026-0212",
  "transactionType": "DELIVERY_NOTE",
  "updatedAt": "2026-11-19T11:30:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/delivery-notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10","currency":"EUR","headerText":"Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.","items":[{"articleNumber":"LNVT14G5","discountPercent":3,"name":"Lenovo ThinkPad T14 Gen 5","positionType":"normal","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":1249},{"isOptional":true,"isSelected":false,"name":"Docking Station USB-C","positionType":"optional","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":189}],"recipientAddress":{"city":"Berlin","country":"DE","street":"Hauptstraße 12","zip":"10115"},"recipientCompany":"Muster GmbH","recipientEmail":"einkauf@muster-gmbh.de","recipientName":"Erika Mustermann","transactionType":"OFFER","validUntil":"2026-11-30T00:00:00Z"}'
```

## Cancel a delivery note (tenant:trade:sales:write)

`POST /api/trade/v1/sales/delivery-notes/{id}/cancel`

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

Sets the delivery note to `CANCELLED`: its quantities are open on the order again and its stock movements are
reversed in the same transaction. A cancelled note is answered unchanged. Refused once the note is invoiced (an
invoice lists it in `typeData.sources`, or the order line would be invoiced beyond its delivered quantity).
Delivery notes made from an order are cancelled, not deleted. The customer's delivery note of a drop shipment
(`typeData.dropShipDelivery`, made from the supplier's delivery) cannot be cancelled (409). Publishes
`trade.deliverynote.cancelled`. No request body.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The transaction (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** The delivery note is invoiced, or it is the delivery note of a drop shipment. (`application/json`)
- **422** The document is no delivery note. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-17T07:45:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-11-17T00:00:00Z",
  "documentDate": "2026-11-17T00:00:00Z",
  "exchangeRate": 1,
  "grossTotal": 2464.49,
  "headerText": "WLAN-Hardware für den Gästebereich",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
  "items": [
    {
      "articleNumber": "NW-2002",
      "id": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
      "lineData": {
        "serialNumbers": [
          "AP6-24K0113",
          "AP6-24K0114",
          "AP6-24K0115",
          "AP6-24K0116",
          "AP6-24K0117",
          "AP6-24K0118"
        ]
      },
      "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "sortOrder": 1,
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "taxRate": 19,
      "totalPriceGross": 1635.06,
      "totalPriceNet": 1374,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
      "unit": "STK",
      "unitPriceNet": 229
    },
    {
      "articleNumber": "NW-2001",
      "id": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
      "lineData": {
        "serialNumbers": [
          "SW24-9K2207"
        ]
      },
      "name": "Switch 24 Port Gigabit PoE+, managed",
      "positionNumber": 2,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "sortOrder": 2,
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e02",
      "taxRate": 19,
      "totalPriceGross": 712.81,
      "totalPriceNet": 599,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
      "unit": "STK",
      "unitPriceNet": 599
    },
    {
      "articleNumber": "NW-2003",
      "id": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f03",
      "name": "Patchkabel Cat.6a 2 m, grau",
      "positionNumber": 3,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "quantity": 20,
      "sortOrder": 3,
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e03",
      "taxRate": 19,
      "totalPriceGross": 116.62,
      "totalPriceNet": 98,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
      "unit": "STK",
      "unitPriceNet": 4.9
    }
  ],
  "netTotal": 2071,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "partnerReference": "Auftrag vom 06.11.2026, K. Stadler",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientName": "Katrin Stadler",
  "sourceKind": "MANUAL",
  "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
  "status": "CANCELLED",
  "taxTotal": 393.49,
  "tenantName": "DEMO",
  "transactionNumber": "LS-2026-0211",
  "transactionType": "DELIVERY_NOTE",
  "updatedAt": "2026-11-17T15:10:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/delivery-notes/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/cancel' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List credit notes (tenant:trade:sales:read)

`GET /api/trade/v1/sales/credit-notes`

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

`listTransactions` with `type=CREDIT_NOTE`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `search` | query | string |  | Substring of the number, the partner's number or the partner name (case-insensitive). |
| `status` | query | string |  | Exact status. |
| `limit` | query | integer |  | Page size; at most 500. (default `50`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** A page of transactions, newest first (creation time, then id); `nextCursor` continues it. (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of Transaction, required)
  - `addressId` (string (uuid)): Masterdata address of the partner.
  - `createdAt` (string (date-time), read-only): When the transaction was created.
  - `currency` (string): ISO 4217; EUR when empty.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `deliveryDate` (string (date-time)): Delivery date.
  - `documentDate` (string (date-time)): Today when empty on create.
  - `documentRefId` (string (uuid)): DMS document of the transaction.
  - `dueDate` (string (date-time)): Due date.
  - `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
  - `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
  - `exchangeRate` (number): 1 when empty.
  - `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
  - `footerText` (string): Text printed below the lines.
  - `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
  - `grossTotal` (number, read-only): Gross total, computed from the lines.
  - `headerText` (string): Text printed above the lines.
  - `id` (string (uuid), read-only): Id of the transaction.
  - `items` (array of TransactionLine): Lines; on update they replace all lines when present.
    - `name` (string, required): Name of the article or line.
    - `quantity` (number, required): Quantity.
    - `articleNumber` (string): Article number in masterdata.
    - `createdAt` (string (date-time), read-only): When the line was created.
    - `description` (string): Description of the line.
    - `discountPercent` (number): Discount in percent.
    - `ean` (string): EAN (GTIN) of the article.
    - `id` (string (uuid), read-only): Id of the line.
    - `isOptional` (boolean): The line is optional (position type `optional`).
    - `isSelected` (boolean): Selected optional lines count in the totals.
    - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
    - `mpn` (string): Manufacturer part number.
    - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
    - `positionNumber` (integer, read-only): Set from the order of `items`.
    - `positionType` (PositionType)
    - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
    - `productId` (string (uuid)): Masterdata article (product) id.
    - `sortOrder` (integer): Sort order (ascending).
    - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
    - `taxRate` (number): Percent.
    - `totalPriceGross` (number, read-only): Gross total of the line, computed.
    - `totalPriceNet` (number, read-only): Net total of the line, computed.
    - `transactionId` (string (uuid), read-only): Id of the transaction.
    - `unit` (string): Unit of measure.
    - `unitPriceNet` (number): Negative for a credit position.
    - `updatedAt` (string (date-time), read-only): When the line was last changed.
  - `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number, read-only): Computed from the lines.
  - `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
  - `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
  - `partnerReference` (string): The partner's order reference (BT-13).
  - `paymentMethodCode` (string): Code of the payment method in masterdata.
  - `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
  - `paymentTermsText` (string): Payment terms as printed text.
  - `predecessorId` (string (uuid)): Previous version of the same document.
  - `recipientAddress` (object): Address snapshot of the partner.
  - `recipientCompany` (string): Company of the recipient.
  - `recipientEmail` (string): E-mail of the recipient.
  - `recipientName` (string): Name of the recipient.
  - `skontoDays1` (integer): Days of the first cash discount.
  - `skontoDays2` (integer): Days of the second cash discount.
  - `skontoRate1` (number): Rate in percent of the first cash discount.
  - `skontoRate2` (number): Rate in percent of the second cash discount.
  - `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
  - `sourceTransactionId` (string (uuid)): Document this one was made from.
  - `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
  - `taxTotal` (number, read-only): Tax total, computed from the lines.
  - `tenantName` (string, read-only): Name of the tenant.
  - `transactionNumber` (string): Assigned with the type's prefix when empty on create.
  - `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
  - `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
  - `updatedAt` (string (date-time), read-only): When the transaction was last changed.
  - `validUntil` (string (date-time)): Offers only.
  - `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
      "createdAt": "2026-11-19T10:12:00Z",
      "currency": "EUR",
      "documentDate": "2026-11-19T00:00:00Z",
      "grossTotal": 272.51,
      "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
      "netTotal": 229,
      "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "status": "DRAFT",
      "taxTotal": 43.51,
      "transactionNumber": "ENTWURF-2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
      "transactionType": "CREDIT_NOTE",
      "updatedAt": "2026-11-19T10:12:00Z",
      "version": 1
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/sales/credit-notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a credit note (tenant:trade:sales:write)

`POST /api/trade/v1/sales/credit-notes`

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

`createTransaction` with `transactionType` set to `CREDIT_NOTE`.

### Request body

`application/json` (required)

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example:

```json
{
  "addressId": "3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10",
  "currency": "EUR",
  "headerText": "Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.",
  "items": [
    {
      "articleNumber": "LNVT14G5",
      "discountPercent": 3,
      "name": "Lenovo ThinkPad T14 Gen 5",
      "positionType": "normal",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 1249
    },
    {
      "isOptional": true,
      "isSelected": false,
      "name": "Docking Station USB-C",
      "positionType": "optional",
      "quantity": 5,
      "taxRate": 19,
      "unit": "Stk",
      "unitPriceNet": 189
    }
  ],
  "recipientAddress": {
    "city": "Berlin",
    "country": "DE",
    "street": "Hauptstraße 12",
    "zip": "10115"
  },
  "recipientCompany": "Muster GmbH",
  "recipientEmail": "einkauf@muster-gmbh.de",
  "recipientName": "Erika Mustermann",
  "transactionType": "OFFER",
  "validUntil": "2026-11-30T00:00:00Z"
}
```

### Responses

- **201** The transaction (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 201 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-19T10:12:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "documentDate": "2026-11-19T00:00:00Z",
  "exchangeRate": 1,
  "grossTotal": 272.51,
  "headerText": "Gutschrift für einen nicht benötigten Access Point (Rücknahme).",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
  "items": [
    {
      "articleNumber": "NW-2002",
      "id": "2f5a6b7c-8d9e-4f0a-9b1c-4d5e6f7a8b01",
      "lineData": {
        "serialNumbers": [
          "AP6-24K0118"
        ]
      },
      "name": "WLAN Access Point Wi-Fi 6 – Rücknahme",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 1,
      "sortOrder": 1,
      "sourceLineId": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01",
      "taxRate": 19,
      "totalPriceGross": 272.51,
      "totalPriceNet": 229,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
      "unit": "STK",
      "unitPriceNet": 229
    }
  ],
  "netDays": 0,
  "netTotal": 229,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "paymentTermsText": "Der Betrag wird Ihnen erstattet.",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientEmail": "buchhaltung@alpenhotel-seeblick.example",
  "recipientName": "Buchhaltung",
  "sourceKind": "MANUAL",
  "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
  "status": "DRAFT",
  "taxTotal": 43.51,
  "tenantName": "DEMO",
  "transactionNumber": "ENTWURF-2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
  "transactionType": "CREDIT_NOTE",
  "typeData": {
    "correctedInvoice": {
      "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "number": "RE-2026-0398"
    },
    "returnToStock": true
  },
  "updatedAt": "2026-11-19T10:12:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/credit-notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10","currency":"EUR","headerText":"Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.","items":[{"articleNumber":"LNVT14G5","discountPercent":3,"name":"Lenovo ThinkPad T14 Gen 5","positionType":"normal","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":1249},{"isOptional":true,"isSelected":false,"name":"Docking Station USB-C","positionType":"optional","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":189}],"recipientAddress":{"city":"Berlin","country":"DE","street":"Hauptstraße 12","zip":"10115"},"recipientCompany":"Muster GmbH","recipientEmail":"einkauf@muster-gmbh.de","recipientName":"Erika Mustermann","transactionType":"OFFER","validUntil":"2026-11-30T00:00:00Z"}'
```

# Transaction types

## List the transaction type catalogue (a trade read permission or tenant:settings:read)

`GET /api/trade/v1/sales/transaction-types`

Module: Trade · operationId: `listTransactionTypes` · Tag: Transaction types · Auth: access token (`Authorization: Bearer <accessToken>`)

All types of the tenant, active and inactive, by sort order.

### Responses

- **200** Types (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of TransactionType, required)
  - `code` (string, read-only): Taken from the path on PUT.
  - `createdAt` (string (date-time), read-only): When the type was created.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `direction` (string): Case-insensitive on input. (one of `IN`, `OUT`)
  - `eInvoiceCode` (string): UNTDID 1001 document type code (BT-3) of e-invoices of this type, or empty; unique per tenant. Inbound e-invoices are filed under the IN type with their code.
  - `isActive` (boolean): The type can be used for new documents.
  - `label` (string): Display name of the type.
  - `metadata` (object): Free-form metadata.
  - `numberPrefix` (string): Prefix of the document numbers.
  - `sortOrder` (integer): Sort order (ascending).
  - `tenantName` (string, read-only): Name of the tenant.
  - `updatedAt` (string (date-time), read-only): When the type was last changed.

Example 200 answer:

```json
{
  "items": [
    {
      "code": "OFFER",
      "direction": "OUT",
      "eInvoiceCode": "",
      "isActive": true,
      "label": "Angebot",
      "numberPrefix": "AN",
      "sortOrder": 10
    },
    {
      "code": "ORDER",
      "direction": "OUT",
      "eInvoiceCode": "",
      "isActive": true,
      "label": "Auftragsbestätigung",
      "numberPrefix": "AB",
      "sortOrder": 20
    },
    {
      "code": "DELIVERY_NOTE",
      "direction": "OUT",
      "eInvoiceCode": "",
      "isActive": true,
      "label": "Lieferschein",
      "numberPrefix": "LS",
      "sortOrder": 30
    },
    {
      "code": "INVOICE",
      "direction": "OUT",
      "eInvoiceCode": "380",
      "isActive": true,
      "label": "Rechnung",
      "numberPrefix": "RE",
      "sortOrder": 40
    },
    {
      "code": "CREDIT_NOTE",
      "direction": "OUT",
      "eInvoiceCode": "381",
      "isActive": true,
      "label": "Gutschrift",
      "numberPrefix": "GS",
      "sortOrder": 50
    },
    {
      "code": "INBOUND_INVOICE",
      "direction": "IN",
      "eInvoiceCode": "380",
      "isActive": true,
      "label": "Eingangsrechnung",
      "numberPrefix": "ER",
      "sortOrder": 70
    },
    {
      "code": "INBOUND_CREDIT_NOTE",
      "direction": "IN",
      "eInvoiceCode": "381",
      "isActive": true,
      "label": "Eingangsgutschrift",
      "numberPrefix": "EG",
      "sortOrder": 75
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/sales/transaction-types' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Reorder the transaction types (tenant:settings:write)

`PATCH /api/trade/v1/sales/transaction-types`

Module: Trade · operationId: `reorderTransactionTypes` · Tag: Transaction types · Auth: access token (`Authorization: Bearer <accessToken>`)

`order` must name every type code of the tenant exactly once; the types get sort orders 10, 20, … in that order. Otherwise nothing is written and the answer is `409`.

### Request body

`application/json` (required)

- `order` (array of string, required)

Example:

```json
{
  "order": [
    "OFFER",
    "ORDER",
    "DELIVERY_NOTE",
    "INVOICE",
    "CREDIT_NOTE",
    "PURCHASE_ORDER",
    "GOODS_RECEIPT",
    "INBOUND_INVOICE",
    "INBOUND_CREDIT_NOTE"
  ]
}
```

### Responses

- **204** Reordered
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **409** The catalogue changed meanwhile; reload. (`application/json`)

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/trade/v1/sales/transaction-types' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"order":["OFFER","ORDER","DELIVERY_NOTE","INVOICE","CREDIT_NOTE","PURCHASE_ORDER","GOODS_RECEIPT","INBOUND_INVOICE","INBOUND_CREDIT_NOTE"]}'
```

## Create or replace a transaction type (tenant:settings:write)

`PUT /api/trade/v1/sales/transaction-types/{code}`

Module: Trade · operationId: `upsertTransactionType` · Tag: Transaction types · Auth: access token (`Authorization: Bearer <accessToken>`)

The code comes from the path. All fields are replaced, including `isActive` and `sortOrder` (omitted values store `false` / `0`). `label` defaults to the code.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `code` | path | string | yes | Type code (upper-cased when stored). |

### Request body

`application/json` (required)

- `code` (string, read-only): Taken from the path on PUT.
- `createdAt` (string (date-time), read-only): When the type was created.
- `customerNo` (string, read-only): Customer number of the tenant.
- `direction` (string): Case-insensitive on input. (one of `IN`, `OUT`)
- `eInvoiceCode` (string): UNTDID 1001 document type code (BT-3) of e-invoices of this type, or empty; unique per tenant. Inbound e-invoices are filed under the IN type with their code.
- `isActive` (boolean): The type can be used for new documents.
- `label` (string): Display name of the type.
- `metadata` (object): Free-form metadata.
- `numberPrefix` (string): Prefix of the document numbers.
- `sortOrder` (integer): Sort order (ascending).
- `tenantName` (string, read-only): Name of the tenant.
- `updatedAt` (string (date-time), read-only): When the type was last changed.

Example:

```json
{
  "direction": "OUT",
  "eInvoiceCode": "",
  "isActive": true,
  "label": "Retoure",
  "numberPrefix": "RT",
  "sortOrder": 90
}
```

### Responses

- **200** Saved (`application/json`)
- **400** `direction` is not `IN`/`OUT` or `eInvoiceCode` is not one to three digits (`fields` names the field). (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **409** Another type of the tenant owns this e-invoice code. (`application/json`)

Fields of the 200 answer:

- `code` (string, read-only): Taken from the path on PUT.
- `createdAt` (string (date-time), read-only): When the type was created.
- `customerNo` (string, read-only): Customer number of the tenant.
- `direction` (string): Case-insensitive on input. (one of `IN`, `OUT`)
- `eInvoiceCode` (string): UNTDID 1001 document type code (BT-3) of e-invoices of this type, or empty; unique per tenant. Inbound e-invoices are filed under the IN type with their code.
- `isActive` (boolean): The type can be used for new documents.
- `label` (string): Display name of the type.
- `metadata` (object): Free-form metadata.
- `numberPrefix` (string): Prefix of the document numbers.
- `sortOrder` (integer): Sort order (ascending).
- `tenantName` (string, read-only): Name of the tenant.
- `updatedAt` (string (date-time), read-only): When the type was last changed.

Example 200 answer:

```json
{
  "code": "INBOUND_CREDIT_NOTE",
  "createdAt": "2026-09-01T07:00:00Z",
  "customerNo": "99999",
  "direction": "IN",
  "eInvoiceCode": "381",
  "isActive": true,
  "label": "Eingangsgutschrift",
  "metadata": {},
  "numberPrefix": "EG",
  "sortOrder": 75,
  "tenantName": "DEMO",
  "updatedAt": "2026-11-10T14:20:00Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/sales/transaction-types/RETURN' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"direction":"OUT","eInvoiceCode":"","isActive":true,"label":"Retoure","numberPrefix":"RT","sortOrder":90}'
```

## Deactivate a transaction type (tenant:settings:write)

`DELETE /api/trade/v1/sales/transaction-types/{code}`

Module: Trade · operationId: `deactivateTransactionType` · Tag: Transaction types · Auth: access token (`Authorization: Bearer <accessToken>`)

Sets `isActive` to false; existing transactions keep their type, new ones of this type are refused.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `code` | path | string | yes | Type code (upper-cased when stored). |

### Responses

- **200** Deactivated (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `status` (string, required): Outcome of the request.

Example 200 answer:

```json
{
  "status": "deactivated"
}
```

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/trade/v1/sales/transaction-types/RETURN' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Issued documents

## List issued invoices (tenant:trade:sales:read)

`GET /api/trade/v1/invoices`

Module: Trade · operationId: `listInvoices` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

The newest 100 transactions of type `INVOICE` in the snapshot shape.

### Responses

- **200** Invoices (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of IssuedInvoice, required)
  - `addressId` (string): Masterdata address of the customer.
  - `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
  - `articleSnapshots` (array of object): Lines as sent. Recognised keys: `articleNumber`, `name`, `description`, `quantity` (default 1), `unit`, `unitPriceNet` (or `price`), `discountPercent`, `taxRate`; the entry is kept as sent.
  - `createdAt` (string (date-time)): When the invoice was created.
  - `customerNo` (string): Customer number of the tenant.
  - `documentDate` (string (date)): Invoice date.
  - `eInvoiceValidation` (EInvoiceValidationSummary): The newest e-invoice check of the invoice (details: `getInvoiceValidation`). Missing without e-invoice.
    - `createdAt` (string (date-time)): When the check ran.
    - `errorCount` (integer): Number of errors.
    - `id` (string (uuid)): Id of the e-invoice check.
    - `valid` (boolean): The document passed the check (no errors).
    - `warningCount` (integer): Number of warnings.
  - `grossTotal` (number): Gross total of the invoice.
  - `id` (string (uuid)): Id of the invoice.
  - `invoiceNumber` (string): Number of the invoice.
  - `netTotal` (number): Net total of the invoice.
  - `numberPending` (boolean): A draft another module made: `invoiceNumber` is its id until `releaseTransaction` numbers it.
  - `partnerName` (string): The customer as the document names it (recipient name, else the name of the address snapshot)
  - `status` (string): Status of the invoice.
  - `tenantName` (string): Name of the tenant.
  - `updatedAt` (string (date-time)): When the invoice was last changed.

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
      "addressSnapshot": {
        "city": "Regensburg",
        "companyName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
        "country": "DE",
        "street": "Maximilianstraße 21",
        "zip": "93047"
      },
      "articleSnapshots": [
        {
          "articleNumber": "WART-STD",
          "name": "IT-Wartung Standard November 2026",
          "quantity": 1,
          "taxRate": 19,
          "unit": "MON",
          "unitPriceNet": 490
        }
      ],
      "createdAt": "2026-11-03T06:00:00Z",
      "customerNo": "99999",
      "documentDate": "2026-11-03",
      "eInvoiceValidation": {
        "createdAt": "2026-11-03T06:00:01Z",
        "errorCount": 0,
        "id": "7c0d1e2f-3a4b-4c5d-8e6f-8a9b0c1d2e03",
        "valid": true,
        "warningCount": 0
      },
      "grossTotal": 583.1,
      "id": "6d9e0f1a-2b3c-4d4e-8f5a-7b8c9d0e1f01",
      "invoiceNumber": "RE-2026-1042",
      "netTotal": 490,
      "numberPending": false,
      "partnerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "status": "issued",
      "tenantName": "DEMO",
      "updatedAt": "2026-11-03T06:00:00Z"
    }
  ]
}
```

### Example request

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

## Get an issued invoice (tenant:trade:sales:read)

`GET /api/trade/v1/invoices/{id}`

Module: Trade · operationId: `getInvoice` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Invoice (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** No invoice with this id (also for transactions of another type). (`application/json`)

Fields of the 200 answer:

- `addressId` (string): Masterdata address of the customer.
- `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
- `articleSnapshots` (array of object): Lines as sent. Recognised keys: `articleNumber`, `name`, `description`, `quantity` (default 1), `unit`, `unitPriceNet` (or `price`), `discountPercent`, `taxRate`; the entry is kept as sent.
- `createdAt` (string (date-time)): When the invoice was created.
- `customerNo` (string): Customer number of the tenant.
- `documentDate` (string (date)): Invoice date.
- `eInvoiceValidation` (EInvoiceValidationSummary): The newest e-invoice check of the invoice (details: `getInvoiceValidation`). Missing without e-invoice.
  - `createdAt` (string (date-time)): When the check ran.
  - `errorCount` (integer): Number of errors.
  - `id` (string (uuid)): Id of the e-invoice check.
  - `valid` (boolean): The document passed the check (no errors).
  - `warningCount` (integer): Number of warnings.
- `grossTotal` (number): Gross total of the invoice.
- `id` (string (uuid)): Id of the invoice.
- `invoiceNumber` (string): Number of the invoice.
- `netTotal` (number): Net total of the invoice.
- `numberPending` (boolean): A draft another module made: `invoiceNumber` is its id until `releaseTransaction` numbers it.
- `partnerName` (string): The customer as the document names it (recipient name, else the name of the address snapshot)
- `status` (string): Status of the invoice.
- `tenantName` (string): Name of the tenant.
- `updatedAt` (string (date-time)): When the invoice was last changed.

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "addressSnapshot": {
    "city": "Regensburg",
    "companyName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
    "country": "DE",
    "street": "Maximilianstraße 21",
    "zip": "93047"
  },
  "articleSnapshots": [
    {
      "articleNumber": "WART-STD",
      "name": "IT-Wartung Standard November 2026",
      "quantity": 1,
      "taxRate": 19,
      "unit": "MON",
      "unitPriceNet": 490
    }
  ],
  "createdAt": "2026-11-03T06:00:00Z",
  "customerNo": "99999",
  "documentDate": "2026-11-03",
  "eInvoiceValidation": {
    "createdAt": "2026-11-03T06:00:01Z",
    "errorCount": 0,
    "id": "7c0d1e2f-3a4b-4c5d-8e6f-8a9b0c1d2e03",
    "valid": true,
    "warningCount": 0
  },
  "grossTotal": 583.1,
  "id": "6d9e0f1a-2b3c-4d4e-8f5a-7b8c9d0e1f01",
  "invoiceNumber": "RE-2026-1042",
  "netTotal": 490,
  "numberPending": false,
  "partnerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "status": "issued",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-03T06:00:00Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Record an issued invoice (tenant:trade:invoice:issue)

`POST /api/trade/v1/invoices/issue`

Module: Trade · operationId: `issueInvoice` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores an invoice the caller issued (status `issued`) with the stated totals and lines from
`articleSnapshots`, and publishes `trade.invoice.issued`. With `recipientEmail` the invoice mail
is queued in the same transaction and sent from the tenant's mail channel (idempotent per invoice).
Payment terms are stored only as stated. `invoiceNumber` and `addressId` are required.

E-invoice: when the customer's address asks for one (masterdata `eInvoiceFormat` other than `PDF`),
`eInvoice` is required (422 `einvoice_required`); an XRechnung customer also needs a Leitweg-ID
(`eInvoiceBuyerRef`, 422 `leitweg_id_required`). If masterdata does not answer within 3 s, the
requirement is not checked and the invoice is recorded. The file is scanned for malware (422 `malware`, 503
when the scan cannot run), validated against the KoSIT rules (EN 16931, XRechnung, CII and UBL) and
stored in DMS with the invoice. With the setting `outbound.eInvoiceValidation` `block` an invalid
e-invoice is refused (422 `einvoice_invalid` with the report), with `warn` (default) the invoice is
issued and `trade.invoice.validation_failed` is raised. The result is `eInvoiceValidation` and
`getInvoiceValidation`.

### Request body

`application/json` (required)

- `addressId` (string (uuid), required): Masterdata address of the customer.
- `invoiceNumber` (string, required): Number of the invoice.
- `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
- `articleSnapshots` (array of object): Lines as sent. Recognised keys: `articleNumber`, `name`, `description`, `quantity` (default 1), `unit`, `unitPriceNet` (or `price`), `discountPercent`, `taxRate`; the entry is kept as sent.
- `eInvoice` (EInvoiceFile): An e-invoice: XRechnung or ZUGFeRD/Factur-X XML (CII or UBL), or a hybrid PDF with embedded invoice XML. At most 10 MB (what the invoice mail can carry).
  - `content` (string (byte), required): The file, base64-encoded.
  - `fileName` (string): Name in DMS and in the mail, without path and control characters, at most 255 bytes; default `Rechnung-<invoiceNumber>.xml`/`.pdf`.
- `grossTotal` (number): Gross total of the invoice.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number): Net total of the invoice.
- `paymentTermCode` (string): Code of the payment terms; without terms the invoice takes the customer's terms from masterdata.
- `paymentTermsText` (string): Payment terms as printed text.
- `recipientEmail` (string (email)): When set, the invoice mail is sent to this address.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.

Example:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "addressSnapshot": {
    "city": "Regensburg",
    "companyName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
    "country": "DE",
    "street": "Maximilianstraße 21",
    "zip": "93047"
  },
  "articleSnapshots": [
    {
      "articleNumber": "WART-STD",
      "name": "IT-Wartung Standard November 2026",
      "quantity": 1,
      "taxRate": 19,
      "unit": "MON",
      "unitPriceNet": 490
    }
  ],
  "grossTotal": 583.1,
  "invoiceNumber": "RE-2026-1042",
  "netDays": 14,
  "netTotal": 490,
  "paymentTermCode": "14N",
  "paymentTermsText": "14 Tage netto",
  "recipientEmail": "f.pichler@hofmann-partner.example"
}
```

### Responses

- **201** Recorded (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** E-invoice refused: `code` is `einvoice_required`, `leitweg_id_required`, `malware` or `einvoice_invalid` (with `details.report`). (`application/json`)
- **500** Error (`application/json`)
- **503** The e-invoice cannot be checked now and is refused: `scan_unavailable` (malware scan) or `einvoice_unavailable` (validation not configured, or the KoSIT validator busy or unavailable – retry later). (`application/json`)

Fields of the 201 answer:

- `addressId` (string): Masterdata address of the customer.
- `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
- `articleSnapshots` (array of object): Lines as sent. Recognised keys: `articleNumber`, `name`, `description`, `quantity` (default 1), `unit`, `unitPriceNet` (or `price`), `discountPercent`, `taxRate`; the entry is kept as sent.
- `createdAt` (string (date-time)): When the invoice was created.
- `customerNo` (string): Customer number of the tenant.
- `documentDate` (string (date)): Invoice date.
- `eInvoiceValidation` (EInvoiceValidationSummary): The newest e-invoice check of the invoice (details: `getInvoiceValidation`). Missing without e-invoice.
  - `createdAt` (string (date-time)): When the check ran.
  - `errorCount` (integer): Number of errors.
  - `id` (string (uuid)): Id of the e-invoice check.
  - `valid` (boolean): The document passed the check (no errors).
  - `warningCount` (integer): Number of warnings.
- `grossTotal` (number): Gross total of the invoice.
- `id` (string (uuid)): Id of the invoice.
- `invoiceNumber` (string): Number of the invoice.
- `netTotal` (number): Net total of the invoice.
- `numberPending` (boolean): A draft another module made: `invoiceNumber` is its id until `releaseTransaction` numbers it.
- `partnerName` (string): The customer as the document names it (recipient name, else the name of the address snapshot)
- `status` (string): Status of the invoice.
- `tenantName` (string): Name of the tenant.
- `updatedAt` (string (date-time)): When the invoice was last changed.

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "addressSnapshot": {
    "city": "Regensburg",
    "companyName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
    "country": "DE",
    "street": "Maximilianstraße 21",
    "zip": "93047"
  },
  "articleSnapshots": [
    {
      "articleNumber": "WART-STD",
      "name": "IT-Wartung Standard November 2026",
      "quantity": 1,
      "taxRate": 19,
      "unit": "MON",
      "unitPriceNet": 490
    }
  ],
  "createdAt": "2026-11-03T06:00:00Z",
  "customerNo": "99999",
  "documentDate": "2026-11-03",
  "eInvoiceValidation": {
    "createdAt": "2026-11-03T06:00:01Z",
    "errorCount": 0,
    "id": "7c0d1e2f-3a4b-4c5d-8e6f-8a9b0c1d2e03",
    "valid": true,
    "warningCount": 0
  },
  "grossTotal": 583.1,
  "id": "6d9e0f1a-2b3c-4d4e-8f5a-7b8c9d0e1f01",
  "invoiceNumber": "RE-2026-1042",
  "netTotal": 490,
  "numberPending": false,
  "partnerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "status": "issued",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-03T06:00:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/invoices/issue' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02","addressSnapshot":{"city":"Regensburg","companyName":"Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB","country":"DE","street":"Maximilianstraße 21","zip":"93047"},"articleSnapshots":[{"articleNumber":"WART-STD","name":"IT-Wartung Standard November 2026","quantity":1,"taxRate":19,"unit":"MON","unitPriceNet":490}],"grossTotal":583.1,"invoiceNumber":"RE-2026-1042","netDays":14,"netTotal":490,"paymentTermCode":"14N","paymentTermsText":"14 Tage netto","recipientEmail":"f.pichler@hofmann-partner.example"}'
```

## Check whether a draft invoice or credit note can be issued (tenant:trade:sales:read)

`GET /api/trade/v1/invoices/{id}/issue/preview`

Module: Trade · operationId: `previewInvoiceIssue` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Names in German what keeps the draft from being issued as XRechnung: the company profile (Einstellungen › Mandant
& Firmenprofil: address, VAT ID or tax number, IBAN, invoice contact, invoice e-mail), the customer's masterdata
address (postal address, e-mail for invoices) and the lines. The KoSIT rules run when it is issued.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Result (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** The document is no draft any more. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `problems` (array of string, required)
- `ready` (boolean, required)

Example 200 answer:

```json
{
  "problems": [
    "Die Rechnungsadresse des Kunden hat keine Postleitzahl.",
    "Im Firmenprofil fehlt die Bankverbindung (IBAN)."
  ],
  "ready": false
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/issue/preview' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get an invoice or credit note as it reads (tenant:trade:sales:read)

`GET /api/trade/v1/invoices/{id}/sheet`

Module: Trade · operationId: `getInvoiceSheet` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

The invoice or credit note in any status as the customer reads it: the document, the seller (company profile with
bank account), the buyer (invoice address of the customer's masterdata), the VAT per rate and what is missing.
`problems` names in German what keeps the sheet incomplete (no company profile, no customer address). Unknown ids
and documents that are no invoice or credit note answer 404; a failing masterdata 502.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The sheet (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `document` (Transaction, required)
  - `addressId` (string (uuid)): Masterdata address of the partner.
  - `createdAt` (string (date-time), read-only): When the transaction was created.
  - `currency` (string): ISO 4217; EUR when empty.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `deliveryDate` (string (date-time)): Delivery date.
  - `documentDate` (string (date-time)): Today when empty on create.
  - `documentRefId` (string (uuid)): DMS document of the transaction.
  - `dueDate` (string (date-time)): Due date.
  - `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
  - `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
  - `exchangeRate` (number): 1 when empty.
  - `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
  - `footerText` (string): Text printed below the lines.
  - `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
  - `grossTotal` (number, read-only): Gross total, computed from the lines.
  - `headerText` (string): Text printed above the lines.
  - `id` (string (uuid), read-only): Id of the transaction.
  - `items` (array of TransactionLine): Lines; on update they replace all lines when present.
    - `name` (string, required): Name of the article or line.
    - `quantity` (number, required): Quantity.
    - `articleNumber` (string): Article number in masterdata.
    - `createdAt` (string (date-time), read-only): When the line was created.
    - `description` (string): Description of the line.
    - `discountPercent` (number): Discount in percent.
    - `ean` (string): EAN (GTIN) of the article.
    - `id` (string (uuid), read-only): Id of the line.
    - `isOptional` (boolean): The line is optional (position type `optional`).
    - `isSelected` (boolean): Selected optional lines count in the totals.
    - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
    - `mpn` (string): Manufacturer part number.
    - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
    - `positionNumber` (integer, read-only): Set from the order of `items`.
    - `positionType` (PositionType)
    - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
    - `productId` (string (uuid)): Masterdata article (product) id.
    - `sortOrder` (integer): Sort order (ascending).
    - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
    - `taxRate` (number): Percent.
    - `totalPriceGross` (number, read-only): Gross total of the line, computed.
    - `totalPriceNet` (number, read-only): Net total of the line, computed.
    - `transactionId` (string (uuid), read-only): Id of the transaction.
    - `unit` (string): Unit of measure.
    - `unitPriceNet` (number): Negative for a credit position.
    - `updatedAt` (string (date-time), read-only): When the line was last changed.
  - `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number, read-only): Computed from the lines.
  - `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
  - `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
  - `partnerReference` (string): The partner's order reference (BT-13).
  - `paymentMethodCode` (string): Code of the payment method in masterdata.
  - `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
  - `paymentTermsText` (string): Payment terms as printed text.
  - `predecessorId` (string (uuid)): Previous version of the same document.
  - `recipientAddress` (object): Address snapshot of the partner.
  - `recipientCompany` (string): Company of the recipient.
  - `recipientEmail` (string): E-mail of the recipient.
  - `recipientName` (string): Name of the recipient.
  - `skontoDays1` (integer): Days of the first cash discount.
  - `skontoDays2` (integer): Days of the second cash discount.
  - `skontoRate1` (number): Rate in percent of the first cash discount.
  - `skontoRate2` (number): Rate in percent of the second cash discount.
  - `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
  - `sourceTransactionId` (string (uuid)): Document this one was made from.
  - `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
  - `taxTotal` (number, read-only): Tax total, computed from the lines.
  - `tenantName` (string, read-only): Name of the tenant.
  - `transactionNumber` (string): Assigned with the type's prefix when empty on create.
  - `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
  - `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
  - `updatedAt` (string (date-time), read-only): When the transaction was last changed.
  - `validUntil` (string (date-time)): Offers only.
  - `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).
- `problems` (array of string, required): What is missing to read the sheet completely, in German.
- `taxes` (array of object, required): VAT per rate of the billable lines, ordered by rate.
  - `net` (number, required): Net amount taxed at the rate.
  - `rate` (number, required): Tax rate in percent.
  - `tax` (number, required): Tax amount at the rate.
- `buyer` (object): Invoice address of the customer (absent without a masterdata address).
  - `name` (string, required): Name of the buyer.
  - `addressLine2` (string): Second address line.
  - `buyerReference` (string): Buyer reference (Leitweg-ID, BT-10).
  - `city` (string): City.
  - `countryCode` (string): Country code (ISO 3166-1 alpha-2).
  - `customerNumber` (string): Customer number of the buyer.
  - `email` (string): E-mail address.
  - `postalCode` (string): Postal code.
  - `street` (string): Street and house number.
  - `vatId` (string): VAT identification number.
- `seller` (object): The tenant's company profile (absent without one).
  - `bankName` (string): Name of the bank.
  - `bic` (string): BIC.
  - `city` (string): City.
  - `commercialRegister` (string): Commercial register number.
  - `companyName` (string): Company name of the seller.
  - `companyNameAddition` (string): Addition to the company name.
  - `contactEmail` (string): E-mail of the contact person.
  - `contactName` (string): Name of the contact person.
  - `contactPhone` (string): Phone of the contact person.
  - `countryCode` (string): Country code (ISO 3166-1 alpha-2).
  - `electronicAddress` (string): Electronic address of the seller (BT-34).
  - `email` (string): E-mail address.
  - `iban` (string): IBAN.
  - `managingDirectors` (string): Managing directors.
  - `phone` (string): Phone number.
  - `postalCode` (string): Postal code.
  - `registerCourt` (string): Register court.
  - `sepaCreditorId` (string): SEPA creditor id.
  - `street` (string): Street and house number.
  - `taxNumber` (string): Tax number.
  - `vatId` (string): VAT identification number.
  - `website` (string): Website.

Example 200 answer:

```json
{
  "buyer": {
    "city": "Schönau am Königssee",
    "countryCode": "DE",
    "customerNumber": "10001",
    "email": "buchhaltung@alpenhotel-seeblick.example",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
    "postalCode": "83471",
    "street": "Seestraße 4"
  },
  "document": {
    "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
    "currency": "EUR",
    "deliveryDate": "2026-11-17T00:00:00Z",
    "documentDate": "2026-11-19T00:00:00Z",
    "dueDate": "2026-12-19T00:00:00Z",
    "grossTotal": 2464.49,
    "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
    "items": [
      {
        "articleNumber": "NW-2002",
        "id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01",
        "lineData": {
          "serialNumbers": [
            "AP6-24K0113",
            "AP6-24K0114",
            "AP6-24K0115",
            "AP6-24K0116",
            "AP6-24K0117",
            "AP6-24K0118"
          ]
        },
        "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
        "positionNumber": 1,
        "positionType": "normal",
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
        "quantity": 6,
        "sortOrder": 1,
        "sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
        "taxRate": 19,
        "totalPriceGross": 1635.06,
        "totalPriceNet": 1374,
        "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
        "unit": "STK",
        "unitPriceNet": 229
      },
      {
        "articleNumber": "NW-2001",
        "id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a02",
        "lineData": {
          "serialNumbers": [
            "SW24-9K2207"
          ]
        },
        "name": "Switch 24 Port Gigabit PoE+, managed",
        "positionNumber": 2,
        "positionType": "normal",
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
        "quantity": 1,
        "sortOrder": 2,
        "sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
        "taxRate": 19,
        "totalPriceGross": 712.81,
        "totalPriceNet": 599,
        "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
        "unit": "STK",
        "unitPriceNet": 599
      },
      {
        "articleNumber": "NW-2003",
        "id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a03",
        "name": "Patchkabel Cat.6a 2 m, grau",
        "positionNumber": 3,
        "positionType": "normal",
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
        "quantity": 20,
        "sortOrder": 3,
        "sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f03",
        "taxRate": 19,
        "totalPriceGross": 116.62,
        "totalPriceNet": 98,
        "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
        "unit": "STK",
        "unitPriceNet": 4.9
      }
    ],
    "netTotal": 2071,
    "partnerReference": "Auftrag vom 06.11.2026, K. Stadler",
    "paymentTermsText": "14 Tage 2 % Skonto, 30 Tage netto",
    "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
    "status": "ISSUED",
    "taxTotal": 393.49,
    "transactionNumber": "RE-2026-0398",
    "transactionType": "INVOICE"
  },
  "problems": [],
  "seller": {
    "bankName": "Deutsche Kreditbank",
    "bic": "BYLADEM1001",
    "city": "Regensburg",
    "commercialRegister": "HRB 15432",
    "companyName": "Muster IT-Systemhaus GmbH",
    "contactEmail": "buchhaltung@muster-it.example",
    "contactName": "Christina Adler",
    "countryCode": "DE",
    "electronicAddress": "rechnung@muster-it.example",
    "email": "info@muster-it.example",
    "iban": "DE02120300000000202051",
    "managingDirectors": "Thomas Pfeiffer",
    "phone": "+49 941 123450",
    "postalCode": "93055",
    "registerCourt": "Amtsgericht Regensburg",
    "street": "Industriestraße 12",
    "taxNumber": "244/123/45678",
    "vatId": "DE999000111",
    "website": "https://www.muster-it.example"
  },
  "taxes": [
    {
      "net": 2071,
      "rate": 19,
      "tax": 393.49
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/sheet' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Issue a draft invoice or credit note (tenant:trade:invoice:issue)

`POST /api/trade/v1/invoices/{id}/issue`

Module: Trade · operationId: `issueInvoiceDraft` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Turns a `DRAFT` invoice or credit note into an issued one (status `ISSUED`) in one database transaction: the next
gapless number of the type (`RE-<year>-<nnnnn>`, credit notes `GS-…`; prefix of the type catalogue), invoice date
today, due date from the net days, an XRechnung 3.0 (CII) written from the seller profile and the customer's
masterdata address and **validated with the KoSIT rules** – an invalid one is refused with its findings and
nothing is numbered –, the XML archived in DMS (`typeData.einvoice`; no PDF any more – documents issued earlier
keep their `pdfDocumentId`), the check listed among the e-invoice checks, and with `send` the mail with the XML
through comms (to `recipient`, else the customer's invoice e-mail). Publishes `trade.invoice.issued`. An issued
document is never changed again.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `recipient` (string (email)): Overrides the customer's invoice e-mail (max length 254)
- `send` (boolean): Mail the invoice to the customer
- `version` (integer): The draft version you read; a newer one answers 409

Example:

```json
{
  "recipient": "buchhaltung@alpenhotel-seeblick.example",
  "send": true,
  "version": 1
}
```

### Responses

- **200** The transaction (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The document is no draft any more, or the draft changed since `version`. (`application/json`)
- **422** Facts are missing (`code: not_ready`, `details.problems`), or the XRechnung fails the KoSIT rules (`code: einvoice_invalid`, `details.findings`). (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid)): Masterdata address of the partner.
- `createdAt` (string (date-time), read-only): When the transaction was created.
- `currency` (string): ISO 4217; EUR when empty.
- `customerNo` (string, read-only): Customer number of the tenant.
- `deliveryDate` (string (date-time)): Delivery date.
- `documentDate` (string (date-time)): Today when empty on create.
- `documentRefId` (string (uuid)): DMS document of the transaction.
- `dueDate` (string (date-time)): Due date.
- `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
- `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
- `exchangeRate` (number): 1 when empty.
- `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
- `footerText` (string): Text printed below the lines.
- `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
- `grossTotal` (number, read-only): Gross total, computed from the lines.
- `headerText` (string): Text printed above the lines.
- `id` (string (uuid), read-only): Id of the transaction.
- `items` (array of TransactionLine): Lines; on update they replace all lines when present.
  - `name` (string, required): Name of the article or line.
  - `quantity` (number, required): Quantity.
  - `articleNumber` (string): Article number in masterdata.
  - `createdAt` (string (date-time), read-only): When the line was created.
  - `description` (string): Description of the line.
  - `discountPercent` (number): Discount in percent.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid), read-only): Id of the line.
  - `isOptional` (boolean): The line is optional (position type `optional`).
  - `isSelected` (boolean): Selected optional lines count in the totals.
  - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
  - `mpn` (string): Manufacturer part number.
  - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
  - `positionNumber` (integer, read-only): Set from the order of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `optional`, `title`, `subtotal`, `text`)
  - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `sortOrder` (integer): Sort order (ascending).
  - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
  - `taxRate` (number): Percent.
  - `totalPriceGross` (number, read-only): Gross total of the line, computed.
  - `totalPriceNet` (number, read-only): Net total of the line, computed.
  - `transactionId` (string (uuid), read-only): Id of the transaction.
  - `unit` (string): Unit of measure.
  - `unitPriceNet` (number): Negative for a credit position.
  - `updatedAt` (string (date-time), read-only): When the line was last changed.
- `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
- `netDays` (integer): Days until the net amount is due.
- `netTotal` (number, read-only): Computed from the lines.
- `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
- `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
- `partnerReference` (string): The partner's order reference (BT-13).
- `paymentMethodCode` (string): Code of the payment method in masterdata.
- `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
- `paymentTermsText` (string): Payment terms as printed text.
- `predecessorId` (string (uuid)): Previous version of the same document.
- `recipientAddress` (object): Address snapshot of the partner.
- `recipientCompany` (string): Company of the recipient.
- `recipientEmail` (string): E-mail of the recipient.
- `recipientName` (string): Name of the recipient.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
- `sourceTransactionId` (string (uuid)): Document this one was made from.
- `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
- `taxTotal` (number, read-only): Tax total, computed from the lines.
- `tenantName` (string, read-only): Name of the tenant.
- `transactionNumber` (string): Assigned with the type's prefix when empty on create.
- `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
- `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `updatedAt` (string (date-time), read-only): When the transaction was last changed.
- `validUntil` (string (date-time)): Offers only.
- `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
  "createdAt": "2026-11-18T08:20:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-11-17T00:00:00Z",
  "documentDate": "2026-11-19T00:00:00Z",
  "dueDate": "2026-12-19T00:00:00Z",
  "exchangeRate": 1,
  "grossTotal": 2464.49,
  "headerText": "Wir berechnen Ihnen die Lieferung vom 17.11.2026:",
  "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
  "items": [
    {
      "articleNumber": "NW-2002",
      "id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01",
      "lineData": {
        "serialNumbers": [
          "AP6-24K0113",
          "AP6-24K0114",
          "AP6-24K0115",
          "AP6-24K0116",
          "AP6-24K0117",
          "AP6-24K0118"
        ]
      },
      "name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "sortOrder": 1,
      "sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
      "taxRate": 19,
      "totalPriceGross": 1635.06,
      "totalPriceNet": 1374,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "unit": "STK",
      "unitPriceNet": 229
    },
    {
      "articleNumber": "NW-2001",
      "id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a02",
      "lineData": {
        "serialNumbers": [
          "SW24-9K2207"
        ]
      },
      "name": "Switch 24 Port Gigabit PoE+, managed",
      "positionNumber": 2,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "sortOrder": 2,
      "sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
      "taxRate": 19,
      "totalPriceGross": 712.81,
      "totalPriceNet": 599,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "unit": "STK",
      "unitPriceNet": 599
    },
    {
      "articleNumber": "NW-2003",
      "id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a03",
      "name": "Patchkabel Cat.6a 2 m, grau",
      "positionNumber": 3,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "quantity": 20,
      "sortOrder": 3,
      "sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f03",
      "taxRate": 19,
      "totalPriceGross": 116.62,
      "totalPriceNet": 98,
      "transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "unit": "STK",
      "unitPriceNet": 4.9
    }
  ],
  "netDays": 30,
  "netTotal": 2071,
  "opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
  "partnerReference": "Auftrag vom 06.11.2026, K. Stadler",
  "paymentTermCode": "14T2",
  "paymentTermsText": "14 Tage 2 % Skonto, 30 Tage netto",
  "recipientAddress": {
    "city": "Schönau am Königssee",
    "country": "DE",
    "street": "Seestraße 4",
    "zip": "83471"
  },
  "recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "recipientEmail": "buchhaltung@alpenhotel-seeblick.example",
  "recipientName": "Buchhaltung",
  "skontoDays1": 14,
  "skontoRate1": 2,
  "sourceKind": "MANUAL",
  "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
  "status": "ISSUED",
  "taxTotal": 393.49,
  "tenantName": "DEMO",
  "transactionNumber": "RE-2026-0398",
  "transactionType": "INVOICE",
  "typeData": {
    "einvoice": {
      "fileName": "RE-2026-0398.xml",
      "xmlDocumentId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c01"
    },
    "sources": [
      {
        "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
        "number": "LS-2026-0211",
        "orderNumber": "AB-2026-0143",
        "partnerReference": "Auftrag vom 06.11.2026, K. Stadler",
        "type": "DELIVERY_NOTE"
      }
    ]
  },
  "updatedAt": "2026-11-19T09:05:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/issue' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"recipient":"buchhaltung@alpenhotel-seeblick.example","send":true,"version":1}'
```

## Get the e-invoice check of an issued invoice (tenant:trade:sales:read)

`GET /api/trade/v1/invoices/{id}/validation`

Module: Trade · operationId: `getInvoiceValidation` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

The newest check of the e-invoice sent with the invoice, with all findings.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Check (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** No invoice with this id, or it was issued without e-invoice. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the check ran.
- `customerNo` (string): Customer number of the tenant.
- `customizationId` (string): Customization id (BT-24) of the e-invoice.
- `dmsDocumentId` (string): The checked file in DMS (empty when it was refused).
- `documentNumber` (string): Invoice or document number (Belegnummer).
- `documentType` (string): microtech transaction type, e.g. Rechnung I.
- `engineVersion` (string): Version of the validator.
- `errorCount` (integer): Number of errors.
- `fileName` (string): File name of the checked XML.
- `findings` (array of EInvoiceFinding): Findings of the validation.
  - `location` (string): XPath of the element; for schema errors the element path with line and column.
  - `message` (string): Message of the rule.
  - `ruleId` (string): Rule of EN 16931 or XRechnung (e.g. BR-DE-15), a schema error code of the validator (e.g. cvc-complex-type.2.4.a: violates the XML schema; the rules did not run), generic-error (not well-formed XML), no-scenario (no validation scenario fits the document), processing-error or PROCESSING_ERROR (the validator could not process it), KOSIT-NOT-XML, TRADE-MALWARE, TRADE-UNREADABLE (a microtech e-invoice that could not be read or checked).
  - `severity` (string): Severity of the finding (e.g. `error`, `warning`). (one of `error`, `warning`, `information`)
- `id` (string (uuid)): Id of the e-invoice check.
- `invoiceId` (string (uuid)): The issued invoice (source issue).
- `mode` (string): The tenant setting applied to an issued invoice. (one of `warn`, `block`, ``)
- `rulesVersion` (string): Version of the validation rules.
- `scenario` (string): KoSIT scenario the document was validated with.
- `source` (string): What was checked: `issue` (issued in trade) or `microtech` (synchronised from the ERP). (one of `issue`, `microtech`)
- `syntax` (string): Syntax of the e-invoice (e.g. UBL, CII).
- `tenantName` (string): Name of the tenant.
- `valid` (boolean): The document passed the check (no errors).
- `warningCount` (integer): Number of warnings.

Example 200 answer:

```json
{
  "createdAt": "2026-11-19T09:05:00Z",
  "customerNo": "99999",
  "customizationId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "dmsDocumentId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c01",
  "documentNumber": "RE-2026-0398",
  "engineVersion": "1.5.0",
  "errorCount": 0,
  "fileName": "RE-2026-0398.xml",
  "findings": [
    {
      "location": "/rsm:CrossIndustryInvoice/rsm:ExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID",
      "message": "Das Element \"Specification identifier\" (BT-24) soll syntaktisch der Kennung des Standards XRechnung entsprechen.",
      "ruleId": "BR-DE-21",
      "severity": "warning"
    }
  ],
  "id": "7c0d1e2f-3a4b-4c5d-8e6f-8a9b0c1d2e01",
  "invoiceId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
  "mode": "warn",
  "rulesVersion": "xrechnung-3.0.2",
  "scenario": "EN16931 XRechnung (CII)",
  "source": "issue",
  "syntax": "CII",
  "tenantName": "DEMO",
  "valid": true,
  "warningCount": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/validation' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List e-invoice checks (tenant:trade:sales:read)

`GET /api/trade/v1/invoice-validations`

Module: Trade · operationId: `listInvoiceValidations` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

The newest check of each e-invoice, newest first: invoices issued through `issueInvoice` (`source=issue`)
and invoices booked in microtech (`source=microtech`, setting `outbound.eInvoiceMicrotechCheck`). Pages by keyset
(creation time, then id; `nextCursor`), `total` counts all matches.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `source` | query | string |  | (one of `issue`, `microtech`) |
| `status` | query | string |  | `invalid`: only checks with errors. (one of `invalid`) |
| `q` | query | string |  | Search in document number, file name and document type (case-insensitive substring). |
| `limit` | query | integer |  | (default `50`; max 200) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** A page of checks and the number of all matching ones. (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of EInvoiceValidation, required): The checks, newest first.
  - `createdAt` (string (date-time)): When the check ran.
  - `customerNo` (string): Customer number of the tenant.
  - `customizationId` (string): Customization id (BT-24) of the e-invoice.
  - `dmsDocumentId` (string): The checked file in DMS (empty when it was refused).
  - `documentNumber` (string): Invoice or document number (Belegnummer).
  - `documentType` (string): microtech transaction type, e.g. Rechnung I.
  - `engineVersion` (string): Version of the validator.
  - `errorCount` (integer): Number of errors.
  - `fileName` (string): File name of the checked XML.
  - `findings` (array of EInvoiceFinding): Findings of the validation.
    - `location` (string): XPath of the element; for schema errors the element path with line and column.
    - `message` (string): Message of the rule.
    - `ruleId` (string): Rule of EN 16931 or XRechnung (e.g. BR-DE-15), a schema error code of the validator (e.g. cvc-complex-type.2.4.a: violates the XML schema; the rules did not run), generic-error (not well-formed XML), no-scenario (no validation scenario fits the document), processing-error or PROCESSING_ERROR (the validator could not process it), KOSIT-NOT-XML, TRADE-MALWARE, TRADE-UNREADABLE (a microtech e-invoice that could not be read or checked).
    - `severity` (string): Severity of the finding (e.g. `error`, `warning`). (one of `error`, `warning`, `information`)
  - `id` (string (uuid)): Id of the e-invoice check.
  - `invoiceId` (string (uuid)): The issued invoice (source issue).
  - `mode` (string): The tenant setting applied to an issued invoice. (one of `warn`, `block`, ``)
  - `rulesVersion` (string): Version of the validation rules.
  - `scenario` (string): KoSIT scenario the document was validated with.
  - `source` (string): What was checked: `issue` (issued in trade) or `microtech` (synchronised from the ERP). (one of `issue`, `microtech`)
  - `syntax` (string): Syntax of the e-invoice (e.g. UBL, CII).
  - `tenantName` (string): Name of the tenant.
  - `valid` (boolean): The document passed the check (no errors).
  - `warningCount` (integer): Number of warnings.
- `total` (integer, required): Number of all checks matching the filters.
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-19T09:05:00Z",
      "customerNo": "99999",
      "customizationId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
      "dmsDocumentId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c01",
      "documentNumber": "RE-2026-0398",
      "engineVersion": "1.5.0",
      "errorCount": 0,
      "fileName": "RE-2026-0398.xml",
      "findings": [
        {
          "location": "/rsm:CrossIndustryInvoice/rsm:ExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID",
          "message": "Das Element \"Specification identifier\" (BT-24) soll syntaktisch der Kennung des Standards XRechnung entsprechen.",
          "ruleId": "BR-DE-21",
          "severity": "warning"
        }
      ],
      "id": "7c0d1e2f-3a4b-4c5d-8e6f-8a9b0c1d2e01",
      "invoiceId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
      "mode": "warn",
      "rulesVersion": "xrechnung-3.0.2",
      "scenario": "EN16931 XRechnung (CII)",
      "source": "issue",
      "syntax": "CII",
      "tenantName": "DEMO",
      "valid": true,
      "warningCount": 1
    },
    {
      "createdAt": "2026-11-12T22:15:00Z",
      "customerNo": "99999",
      "customizationId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
      "dmsDocumentId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c02",
      "documentNumber": "RE-2026-0377",
      "documentType": "Rechnung I",
      "engineVersion": "1.5.0",
      "errorCount": 1,
      "fileName": "RE-2026-0377.xml",
      "findings": [
        {
          "location": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement",
          "message": "Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
          "ruleId": "BR-DE-15",
          "severity": "error"
        }
      ],
      "id": "7c0d1e2f-3a4b-4c5d-8e6f-8a9b0c1d2e02",
      "mode": "",
      "rulesVersion": "xrechnung-3.0.2",
      "scenario": "EN16931 XRechnung (CII)",
      "source": "microtech",
      "syntax": "CII",
      "tenantName": "DEMO",
      "valid": false,
      "warningCount": 0
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/invoice-validations' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get an e-invoice check (tenant:trade:sales:read)

`GET /api/trade/v1/invoice-validations/{id}`

Module: Trade · operationId: `getInvoiceValidationById` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Check (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** No check with this id. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the check ran.
- `customerNo` (string): Customer number of the tenant.
- `customizationId` (string): Customization id (BT-24) of the e-invoice.
- `dmsDocumentId` (string): The checked file in DMS (empty when it was refused).
- `documentNumber` (string): Invoice or document number (Belegnummer).
- `documentType` (string): microtech transaction type, e.g. Rechnung I.
- `engineVersion` (string): Version of the validator.
- `errorCount` (integer): Number of errors.
- `fileName` (string): File name of the checked XML.
- `findings` (array of EInvoiceFinding): Findings of the validation.
  - `location` (string): XPath of the element; for schema errors the element path with line and column.
  - `message` (string): Message of the rule.
  - `ruleId` (string): Rule of EN 16931 or XRechnung (e.g. BR-DE-15), a schema error code of the validator (e.g. cvc-complex-type.2.4.a: violates the XML schema; the rules did not run), generic-error (not well-formed XML), no-scenario (no validation scenario fits the document), processing-error or PROCESSING_ERROR (the validator could not process it), KOSIT-NOT-XML, TRADE-MALWARE, TRADE-UNREADABLE (a microtech e-invoice that could not be read or checked).
  - `severity` (string): Severity of the finding (e.g. `error`, `warning`). (one of `error`, `warning`, `information`)
- `id` (string (uuid)): Id of the e-invoice check.
- `invoiceId` (string (uuid)): The issued invoice (source issue).
- `mode` (string): The tenant setting applied to an issued invoice. (one of `warn`, `block`, ``)
- `rulesVersion` (string): Version of the validation rules.
- `scenario` (string): KoSIT scenario the document was validated with.
- `source` (string): What was checked: `issue` (issued in trade) or `microtech` (synchronised from the ERP). (one of `issue`, `microtech`)
- `syntax` (string): Syntax of the e-invoice (e.g. UBL, CII).
- `tenantName` (string): Name of the tenant.
- `valid` (boolean): The document passed the check (no errors).
- `warningCount` (integer): Number of warnings.

Example 200 answer:

```json
{
  "createdAt": "2026-11-19T09:05:00Z",
  "customerNo": "99999",
  "customizationId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "dmsDocumentId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c01",
  "documentNumber": "RE-2026-0398",
  "engineVersion": "1.5.0",
  "errorCount": 0,
  "fileName": "RE-2026-0398.xml",
  "findings": [
    {
      "location": "/rsm:CrossIndustryInvoice/rsm:ExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID",
      "message": "Das Element \"Specification identifier\" (BT-24) soll syntaktisch der Kennung des Standards XRechnung entsprechen.",
      "ruleId": "BR-DE-21",
      "severity": "warning"
    }
  ],
  "id": "7c0d1e2f-3a4b-4c5d-8e6f-8a9b0c1d2e01",
  "invoiceId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
  "mode": "warn",
  "rulesVersion": "xrechnung-3.0.2",
  "scenario": "EN16931 XRechnung (CII)",
  "source": "issue",
  "syntax": "CII",
  "tenantName": "DEMO",
  "valid": true,
  "warningCount": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/invoice-validations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List offers in the snapshot shape (tenant:trade:sales:read)

`GET /api/trade/v1/offers`

Module: Trade · operationId: `listIssuedOffers` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

The newest 100 transactions of type `OFFER`.

### Responses

- **200** Offers (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of IssuedOffer, required)
  - `addressId` (string): Masterdata address of the customer.
  - `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
  - `articleSnapshots` (array of object): Lines as sent. Recognised keys: `articleNumber`, `name`, `description`, `quantity` (default 1), `unit`, `unitPriceNet` (or `price`), `discountPercent`, `taxRate`; the entry is kept as sent.
  - `createdAt` (string (date-time)): When the offer was created.
  - `customerNo` (string): Customer number of the tenant.
  - `id` (string (uuid)): Id of the offer.
  - `offerNumber` (string): Number of the offer.
  - `status` (string): Status of the offer.
  - `tenantName` (string): Name of the tenant.
  - `totalAmount` (number): Total of the offer.

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
      "addressSnapshot": {
        "city": "Neutraubling",
        "companyName": "Donau Maschinenbau AG",
        "country": "DE",
        "street": "Werkstraße 100",
        "zip": "93073"
      },
      "articleSnapshots": [
        {
          "articleNumber": "HW-1002",
          "name": "Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD",
          "quantity": 4,
          "taxRate": 19,
          "unitPriceNet": 1699
        },
        {
          "articleNumber": "HW-1004",
          "name": "USB-C Dockingstation 100 W",
          "quantity": 4,
          "taxRate": 19,
          "unitPriceNet": 189
        }
      ],
      "createdAt": "2026-11-18T14:05:00Z",
      "customerNo": "99999",
      "id": "6d9e0f1a-2b3c-4d4e-8f5a-7b8c9d0e1f02",
      "offerNumber": "AN-2026-0188",
      "status": "open",
      "tenantName": "DEMO",
      "totalAmount": 7552
    }
  ]
}
```

### Example request

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

## Record an offer from snapshots (tenant:trade:sales:write)

`POST /api/trade/v1/offers`

Module: Trade · operationId: `createIssuedOffer` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores an `OFFER` with status `open`; `totalAmount` is stored as the net total. Publishes `trade.offer.created`.

### Request body

`application/json` (required)

- `addressId` (string (uuid)): Masterdata address of the customer.
- `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
- `articleSnapshots` (array of object): Lines as sent. Recognised keys: `articleNumber`, `name`, `description`, `quantity` (default 1), `unit`, `unitPriceNet` (or `price`), `discountPercent`, `taxRate`; the entry is kept as sent.
- `offerNumber` (string): Number of the offer.
- `totalAmount` (number): Net total.

Example:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
  "addressSnapshot": {
    "city": "Neutraubling",
    "companyName": "Donau Maschinenbau AG",
    "country": "DE",
    "street": "Werkstraße 100",
    "zip": "93073"
  },
  "articleSnapshots": [
    {
      "articleNumber": "HW-1002",
      "name": "Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD",
      "quantity": 4,
      "taxRate": 19,
      "unitPriceNet": 1699
    },
    {
      "articleNumber": "HW-1004",
      "name": "USB-C Dockingstation 100 W",
      "quantity": 4,
      "taxRate": 19,
      "unitPriceNet": 189
    }
  ],
  "offerNumber": "AN-2026-0188",
  "totalAmount": 7552
}
```

### Responses

- **201** Recorded (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 201 answer:

- `addressId` (string): Masterdata address of the customer.
- `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
- `articleSnapshots` (array of object): Lines as sent. Recognised keys: `articleNumber`, `name`, `description`, `quantity` (default 1), `unit`, `unitPriceNet` (or `price`), `discountPercent`, `taxRate`; the entry is kept as sent.
- `createdAt` (string (date-time)): When the offer was created.
- `customerNo` (string): Customer number of the tenant.
- `id` (string (uuid)): Id of the offer.
- `offerNumber` (string): Number of the offer.
- `status` (string): Status of the offer.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Total of the offer.

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
  "addressSnapshot": {
    "city": "Neutraubling",
    "companyName": "Donau Maschinenbau AG",
    "country": "DE",
    "street": "Werkstraße 100",
    "zip": "93073"
  },
  "articleSnapshots": [
    {
      "articleNumber": "HW-1002",
      "name": "Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD",
      "quantity": 4,
      "taxRate": 19,
      "unitPriceNet": 1699
    },
    {
      "articleNumber": "HW-1004",
      "name": "USB-C Dockingstation 100 W",
      "quantity": 4,
      "taxRate": 19,
      "unitPriceNet": 189
    }
  ],
  "createdAt": "2026-11-18T14:05:00Z",
  "customerNo": "99999",
  "id": "6d9e0f1a-2b3c-4d4e-8f5a-7b8c9d0e1f02",
  "offerNumber": "AN-2026-0188",
  "status": "open",
  "tenantName": "DEMO",
  "totalAmount": 7552
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/offers' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05","addressSnapshot":{"city":"Neutraubling","companyName":"Donau Maschinenbau AG","country":"DE","street":"Werkstraße 100","zip":"93073"},"articleSnapshots":[{"articleNumber":"HW-1002","name":"Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD","quantity":4,"taxRate":19,"unitPriceNet":1699},{"articleNumber":"HW-1004","name":"USB-C Dockingstation 100 W","quantity":4,"taxRate":19,"unitPriceNet":189}],"offerNumber":"AN-2026-0188","totalAmount":7552}'
```

## List orders in the snapshot shape (tenant:trade:sales:read)

`GET /api/trade/v1/orders`

Module: Trade · operationId: `listIssuedOrders` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

The newest 100 transactions of type `ORDER`.

### Responses

- **200** Orders (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of IssuedOrder, required)
  - `addressId` (string): Masterdata address of the customer.
  - `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
  - `articleSnapshots` (array of object): Lines as sent. Recognised keys: `articleNumber`, `name`, `description`, `quantity` (default 1), `unit`, `unitPriceNet` (or `price`), `discountPercent`, `taxRate`; the entry is kept as sent.
  - `createdAt` (string (date-time)): When the order was created.
  - `customerNo` (string): Customer number of the tenant.
  - `id` (string (uuid)): Id of the order.
  - `orderNumber` (string): Number of the order.
  - `status` (string): Status of the order.
  - `tenantName` (string): Name of the tenant.

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
      "addressSnapshot": {
        "city": "Neutraubling",
        "companyName": "Donau Maschinenbau AG",
        "country": "DE",
        "street": "Werkstraße 100",
        "zip": "93073"
      },
      "articleSnapshots": [
        {
          "articleNumber": "HW-1002",
          "name": "Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD",
          "quantity": 4,
          "taxRate": 19,
          "unitPriceNet": 1699
        },
        {
          "articleNumber": "HW-1004",
          "name": "USB-C Dockingstation 100 W",
          "quantity": 4,
          "taxRate": 19,
          "unitPriceNet": 189
        }
      ],
      "createdAt": "2026-11-19T08:10:00Z",
      "customerNo": "99999",
      "id": "6d9e0f1a-2b3c-4d4e-8f5a-7b8c9d0e1f03",
      "orderNumber": "AB-2026-0144",
      "status": "open",
      "tenantName": "DEMO"
    }
  ]
}
```

### Example request

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

## Record an order from snapshots (tenant:trade:sales:write)

`POST /api/trade/v1/orders`

Module: Trade · operationId: `createIssuedOrder` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores an `ORDER` with status `open`. Publishes `trade.order.created`.

### Request body

`application/json` (required)

- `addressId` (string (uuid)): Masterdata address of the customer.
- `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
- `articleSnapshots` (array of object): Lines as sent. Recognised keys: `articleNumber`, `name`, `description`, `quantity` (default 1), `unit`, `unitPriceNet` (or `price`), `discountPercent`, `taxRate`; the entry is kept as sent.
- `orderNumber` (string): Number of the order.

Example:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
  "addressSnapshot": {
    "city": "Neutraubling",
    "companyName": "Donau Maschinenbau AG",
    "country": "DE",
    "street": "Werkstraße 100",
    "zip": "93073"
  },
  "articleSnapshots": [
    {
      "articleNumber": "HW-1002",
      "name": "Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD",
      "quantity": 4,
      "taxRate": 19,
      "unitPriceNet": 1699
    },
    {
      "articleNumber": "HW-1004",
      "name": "USB-C Dockingstation 100 W",
      "quantity": 4,
      "taxRate": 19,
      "unitPriceNet": 189
    }
  ],
  "orderNumber": "AB-2026-0144"
}
```

### Responses

- **201** Recorded (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 201 answer:

- `addressId` (string): Masterdata address of the customer.
- `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
- `articleSnapshots` (array of object): Lines as sent. Recognised keys: `articleNumber`, `name`, `description`, `quantity` (default 1), `unit`, `unitPriceNet` (or `price`), `discountPercent`, `taxRate`; the entry is kept as sent.
- `createdAt` (string (date-time)): When the order was created.
- `customerNo` (string): Customer number of the tenant.
- `id` (string (uuid)): Id of the order.
- `orderNumber` (string): Number of the order.
- `status` (string): Status of the order.
- `tenantName` (string): Name of the tenant.

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
  "addressSnapshot": {
    "city": "Neutraubling",
    "companyName": "Donau Maschinenbau AG",
    "country": "DE",
    "street": "Werkstraße 100",
    "zip": "93073"
  },
  "articleSnapshots": [
    {
      "articleNumber": "HW-1002",
      "name": "Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD",
      "quantity": 4,
      "taxRate": 19,
      "unitPriceNet": 1699
    },
    {
      "articleNumber": "HW-1004",
      "name": "USB-C Dockingstation 100 W",
      "quantity": 4,
      "taxRate": 19,
      "unitPriceNet": 189
    }
  ],
  "createdAt": "2026-11-19T08:10:00Z",
  "customerNo": "99999",
  "id": "6d9e0f1a-2b3c-4d4e-8f5a-7b8c9d0e1f03",
  "orderNumber": "AB-2026-0144",
  "status": "open",
  "tenantName": "DEMO"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/orders' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05","addressSnapshot":{"city":"Neutraubling","companyName":"Donau Maschinenbau AG","country":"DE","street":"Werkstraße 100","zip":"93073"},"articleSnapshots":[{"articleNumber":"HW-1002","name":"Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD","quantity":4,"taxRate":19,"unitPriceNet":1699},{"articleNumber":"HW-1004","name":"USB-C Dockingstation 100 W","quantity":4,"taxRate":19,"unitPriceNet":189}],"orderNumber":"AB-2026-0144"}'
```

## List delivery notes in the snapshot shape (tenant:trade:sales:read)

`GET /api/trade/v1/delivery-notes`

Module: Trade · operationId: `listIssuedDeliveryNotes` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

The newest 100 transactions of type `DELIVERY_NOTE`.

### Responses

- **200** Delivery notes (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of IssuedDeliveryNote, required)
  - `addressId` (string): Masterdata address of the customer.
  - `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
  - `createdAt` (string (date-time)): When the delivery note was created.
  - `customerNo` (string): Customer number of the tenant.
  - `deliveryNoteNumber` (string): Number of the delivery note.
  - `id` (string (uuid)): Id of the delivery note.
  - `status` (string): Status of the delivery note.
  - `tenantName` (string): Name of the tenant.

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
      "addressSnapshot": {
        "city": "Neutraubling",
        "companyName": "Donau Maschinenbau AG",
        "country": "DE",
        "street": "Werkstraße 100",
        "zip": "93073"
      },
      "createdAt": "2026-11-19T13:40:00Z",
      "customerNo": "99999",
      "deliveryNoteNumber": "LS-2026-0213",
      "id": "6d9e0f1a-2b3c-4d4e-8f5a-7b8c9d0e1f04",
      "status": "delivered",
      "tenantName": "DEMO"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/delivery-notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Record a delivery note from snapshots (tenant:trade:sales:write)

`POST /api/trade/v1/delivery-notes`

Module: Trade · operationId: `createIssuedDeliveryNote` · Tag: Issued documents · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores a `DELIVERY_NOTE` with status `delivered`. Publishes `trade.deliverynote.created`.

### Request body

`application/json` (required)

- `addressId` (string (uuid)): Masterdata address of the customer.
- `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
- `deliveryNoteNumber` (string): Number of the delivery note.

Example:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
  "addressSnapshot": {
    "city": "Neutraubling",
    "companyName": "Donau Maschinenbau AG",
    "country": "DE",
    "street": "Werkstraße 100",
    "zip": "93073"
  },
  "deliveryNoteNumber": "LS-2026-0213"
}
```

### Responses

- **201** Recorded (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 201 answer:

- `addressId` (string): Masterdata address of the customer.
- `addressSnapshot` (AddressSnapshot): Frozen copy of the partner address (GoBD).
- `createdAt` (string (date-time)): When the delivery note was created.
- `customerNo` (string): Customer number of the tenant.
- `deliveryNoteNumber` (string): Number of the delivery note.
- `id` (string (uuid)): Id of the delivery note.
- `status` (string): Status of the delivery note.
- `tenantName` (string): Name of the tenant.

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
  "addressSnapshot": {
    "city": "Neutraubling",
    "companyName": "Donau Maschinenbau AG",
    "country": "DE",
    "street": "Werkstraße 100",
    "zip": "93073"
  },
  "createdAt": "2026-11-19T13:40:00Z",
  "customerNo": "99999",
  "deliveryNoteNumber": "LS-2026-0213",
  "id": "6d9e0f1a-2b3c-4d4e-8f5a-7b8c9d0e1f04",
  "status": "delivered",
  "tenantName": "DEMO"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/delivery-notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05","addressSnapshot":{"city":"Neutraubling","companyName":"Donau Maschinenbau AG","country":"DE","street":"Werkstraße 100","zip":"93073"},"deliveryNoteNumber":"LS-2026-0213"}'
```

# Inbound invoices

## List inbound invoices (tenant:trade:inbound:read)

`GET /api/trade/v1/inbound-invoices`

Module: Trade · operationId: `listInboundInvoices` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

Newest first (creation time, then id), without OCR text and lines; pages by keyset (`nextCursor`), `total` counts all matches.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string |  | One status or a comma-separated list (case-insensitive), e.g. `MATCHED,DISCREPANCY`. |
| `q` | query | string |  | Substring of the internal number, the supplier's invoice number or the supplier name. |
| `limit` | query | integer |  | 1–200 (else `400 invalid`). (default `50`; max 200) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** Invoices (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of InboundInvoice, required): The inbound invoices of the page.
  - `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
    - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
    - `extracted` (object): The supplier as read from the document.
    - `supplier` (object): The assigned master data supplier.
    - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
      - `cached` (boolean): The result came from the 24-hour cache of master data.
      - `checkedAt` (string (date-time)): When the VAT id was checked.
      - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
      - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
      - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
      - `statusDisplay` (string): The status as German text.
      - `statusMessage` (string): Message of the checking service, if any.
      - `vatId` (string): VAT id checked.
  - `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
    - `eligible` (boolean): Every condition holds.
    - `evaluatedAt` (string (date-time)): When the decision was evaluated.
    - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
    - `reasons` (array of string): Each failed condition (German text).
    - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
    - `rule` (string): The rule that applied, also the protocol note of the release.
    - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
  - `createdAt` (string (date-time)): When the inbound invoice was created.
  - `currency` (string): Currency (ISO 4217).
  - `customerNo` (string): Customer number of the tenant.
  - `deliveryDate` (string (date)): Delivery date.
  - `dmsDocumentId` (string (uuid)): DMS document of the invoice.
  - `dueDate` (string (date)): Due date.
  - `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
  - `error` (string): Why processing failed (status `FAILED`).
  - `exchangeRate` (number): Exchange rate to EUR.
  - `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
    - `confidence` (object): Per field (AI extraction only).
    - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
    - `currency` (string): Currency (ISO 4217).
    - `customerNumber` (string): Our customer number at the supplier.
    - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
    - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
    - `discountTerms` (array of object): Cash discount terms.
      - `days` (integer): Days within which the discount applies.
      - `percent` (number): Discount in percent.
    - `discountText` (string): Cash discount terms as printed.
    - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
    - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
    - `dueDate` (string): Due date (YYYY-MM-DD).
    - `grossTotal` (number): Gross total.
    - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
    - `invoiceNumber` (string): Invoice number.
    - `isReverseCharge` (boolean): The invoice is reverse charge.
    - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
    - `netDays` (integer): Days until the net amount is due.
    - `netTotal` (number): Net total.
    - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
    - `orderNumber` (string): Order number stated on the invoice.
    - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
    - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
    - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
    - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
    - `recipient` (Party)
    - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
    - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
    - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
    - `taxExemptionReason` (string): Stated reason for a tax exemption.
    - `taxRates` (array of object): Tax breakdown per rate.
      - `netAmount` (number): Net amount taxed at the rate.
      - `rate` (number): Tax rate in percent.
      - `taxAmount` (number): Tax amount at the rate.
    - `taxTotal` (number): Tax total.
    - `vendor` (Party)
  - `fullText` (string): OCR text (single invoice only).
  - `id` (string (uuid)): Id of the inbound invoice.
  - `invoiceDate` (string (date)): Invoice date.
  - `invoiceNumber` (string): The supplier's invoice number.
  - `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchResult` (MatchResult)
    - `evaluatedAt` (string (date-time)): When the match ran.
    - `isBlocked` (boolean): A blocking lock reason was found.
    - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
    - `lockReasons` (array of LockReason): Lock reasons found.
    - `matchedLines` (array of object): Result per invoice line.
      - `articleNumber` (string): Article number in masterdata.
      - `availableQty` (number): Received minus already invoiced.
      - `description` (string): Description of the line.
      - `invoicePosition` (integer): Position on the invoice.
      - `invoicedPrice` (number): Unit price invoiced.
      - `invoicedQty` (number): Quantity invoiced.
      - `isMatched` (boolean): The line matches within the tolerances.
      - `poPosition` (integer): Position on the purchase order.
      - `poPrice` (number): Unit price ordered.
      - `poQty` (number): Quantity ordered.
      - `priceVariance` (number): Unit price variance.
      - `qtyVariance` (number): Quantity variance.
      - `receivedQty` (number): Quantity received.
      - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
    - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
    - `totalVariance` (number): Sum of the price variances.
  - `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
  - `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
  - `netTotal` (number): Net total.
  - `partnerReference` (string): Our order number as printed on the invoice.
  - `paymentTermsText` (string): Payment terms as printed text.
  - `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
    - `startedAt` (string (date-time)): When the current processing started.
    - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
  - `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
  - `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
    - `code` (string): Code of the lock reason.
    - `comment` (string): Why it was accepted.
    - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
    - `resolvedAt` (string (date-time)): When it was accepted.
    - `resolvedBy` (string): Who accepted it.
  - `skontoDays1` (integer): Days of the first cash discount.
  - `skontoDays2` (integer): Days of the second cash discount.
  - `skontoRate1` (number): Rate in percent of the first cash discount.
  - `skontoRate2` (number): Rate in percent of the second cash discount.
  - `skontoTerms` (any): Cash discount terms.
  - `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
  - `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
  - `taxTotal` (number): Tax total.
  - `tenantName` (string): Name of the tenant.
  - `totalAmount` (number): Gross total of the invoice.
  - `totalAmountEur` (number): Gross total in EUR (ECB rate).
  - `transactionNumber` (string): Internal number.
  - `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
  - `updatedAt` (string (date-time)): When the inbound invoice was last changed.
  - `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
  - `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
  - `vendorName` (string): Name of the supplier as stated on the invoice.
  - `vendorVatId` (string): Manual correction of the supplier's VAT ID.
- `total` (integer, required): Number of entries of the whole list.
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-10-26T08:35:00Z",
      "currency": "EUR",
      "dueDate": "2026-11-22",
      "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a02",
      "invoiceDate": "2026-10-23",
      "invoiceNumber": "RE-483350",
      "matchingStatus": "blocked",
      "netTotal": 4347,
      "sourceKind": "XRECHNUNG_CII",
      "status": "DISCREPANCY",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "taxTotal": 825.93,
      "totalAmount": 5172.93,
      "transactionNumber": "ER-2026-00036",
      "transactionType": "INBOUND_INVOICE",
      "updatedAt": "2026-10-26T08:36:02Z",
      "vendorName": "Nordlicht IT-Distribution GmbH"
    },
    {
      "createdAt": "2026-10-05T08:40:00Z",
      "currency": "EUR",
      "dueDate": "2026-11-01",
      "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a01",
      "invoiceDate": "2026-10-02",
      "invoiceNumber": "RE-482117",
      "matchingStatus": "matched",
      "netTotal": 5808,
      "sourceKind": "XRECHNUNG_CII",
      "status": "MATCHED",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "taxTotal": 1103.52,
      "totalAmount": 6911.52,
      "transactionNumber": "ER-2026-00031",
      "transactionType": "INBOUND_INVOICE",
      "updatedAt": "2026-10-05T08:41:12Z",
      "vendorName": "Nordlicht IT-Distribution GmbH"
    }
  ],
  "nextCursor": "Y3JlYXRlZHwyMDI2LTEwLTA1VDA4OjQwOjAwWnw4ZTFmMmEzYi00YzVkLTRlNmYtOWE3Yi0wYzFkMmUzZjRhMDE",
  "total": 14
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Process a DMS document as inbound invoice (tenant:trade:inbound:write)

`POST /api/trade/v1/inbound-invoices`

Module: Trade · operationId: `createInboundInvoice` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

Registers an existing DMS document and starts the pipeline when its text extraction is done. The
answer does not wait for the run: it carries `processing` (step `queued`), and the invoice moves on
in the background – read it again until `processing` is gone. Idempotent per document: a document
that already has an invoice beyond `RECEIVED` answers that invoice. Documents normally arrive
automatically from the DMS feed.

### Request body

`application/json` (required)

- `dmsDocumentId` (string (uuid), required)

Example:

```json
{
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b03"
}
```

### Responses

- **201** The invoice (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **422** The DMS document does not exist. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 201 answer:

- `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
  - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
  - `extracted` (object): The supplier as read from the document.
  - `supplier` (object): The assigned master data supplier.
  - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
    - `cached` (boolean): The result came from the 24-hour cache of master data.
    - `checkedAt` (string (date-time)): When the VAT id was checked.
    - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
    - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
    - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
    - `statusDisplay` (string): The status as German text.
    - `statusMessage` (string): Message of the checking service, if any.
    - `vatId` (string): VAT id checked.
- `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
  - `eligible` (boolean): Every condition holds.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `reasons` (array of string): Each failed condition (German text).
  - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
  - `rule` (string): The rule that applied, also the protocol note of the release.
  - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
- `createdAt` (string (date-time)): When the inbound invoice was created.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string): Customer number of the tenant.
- `deliveryDate` (string (date)): Delivery date.
- `dmsDocumentId` (string (uuid)): DMS document of the invoice.
- `dueDate` (string (date)): Due date.
- `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
- `error` (string): Why processing failed (status `FAILED`).
- `exchangeRate` (number): Exchange rate to EUR.
- `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
  - `confidence` (object): Per field (AI extraction only).
  - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
  - `currency` (string): Currency (ISO 4217).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
  - `discountTerms` (array of object): Cash discount terms.
    - `days` (integer): Days within which the discount applies.
    - `percent` (number): Discount in percent.
  - `discountText` (string): Cash discount terms as printed.
  - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
  - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
  - `dueDate` (string): Due date (YYYY-MM-DD).
  - `grossTotal` (number): Gross total.
  - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
  - `invoiceNumber` (string): Invoice number.
  - `isReverseCharge` (boolean): The invoice is reverse charge.
  - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number): Net total.
  - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
  - `orderNumber` (string): Order number stated on the invoice.
  - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
  - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
  - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
  - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
  - `recipient` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
  - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
  - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
  - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `taxExemptionReason` (string): Stated reason for a tax exemption.
  - `taxRates` (array of object): Tax breakdown per rate.
    - `netAmount` (number): Net amount taxed at the rate.
    - `rate` (number): Tax rate in percent.
    - `taxAmount` (number): Tax amount at the rate.
  - `taxTotal` (number): Tax total.
  - `vendor` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text (single invoice only).
- `id` (string (uuid)): Id of the inbound invoice.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): The supplier's invoice number.
- `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
  - `articleAssignment` (object): How the article was resolved.
    - `confidence` (number): Confidence of the article assignment (0–1).
    - `evidence` (string): What the article assignment is based on.
    - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
  - `articleNumber` (string): Internal article number (masterdata).
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `ignored` (boolean): Article on the configured ignore list.
  - `mpn` (string): Manufacturer part number.
  - `netAmount` (number): Net amount of the line.
  - `orderLineRef` (string): Order line the line refers to (BT-132).
  - `orderNumber` (string): Order number the line refers to.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number.
- `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
  - `article` (string): Article of the line.
  - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
  - `description` (string): Human-readable explanation.
  - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
  - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
  - `variance` (number): Variance found (amount or quantity).
- `matchResult` (MatchResult)
  - `evaluatedAt` (string (date-time)): When the match ran.
  - `isBlocked` (boolean): A blocking lock reason was found.
  - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
  - `lockReasons` (array of LockReason): Lock reasons found.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchedLines` (array of object): Result per invoice line.
    - `articleNumber` (string): Article number in masterdata.
    - `availableQty` (number): Received minus already invoiced.
    - `description` (string): Description of the line.
    - `invoicePosition` (integer): Position on the invoice.
    - `invoicedPrice` (number): Unit price invoiced.
    - `invoicedQty` (number): Quantity invoiced.
    - `isMatched` (boolean): The line matches within the tolerances.
    - `poPosition` (integer): Position on the purchase order.
    - `poPrice` (number): Unit price ordered.
    - `poQty` (number): Quantity ordered.
    - `priceVariance` (number): Unit price variance.
    - `qtyVariance` (number): Quantity variance.
    - `receivedQty` (number): Quantity received.
    - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
  - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
  - `totalVariance` (number): Sum of the price variances.
- `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
- `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
- `netTotal` (number): Net total.
- `partnerReference` (string): Our order number as printed on the invoice.
- `paymentTermsText` (string): Payment terms as printed text.
- `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
  - `startedAt` (string (date-time)): When the current processing started.
  - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
- `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
- `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
  - `code` (string): Code of the lock reason.
  - `comment` (string): Why it was accepted.
  - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
  - `resolvedAt` (string (date-time)): When it was accepted.
  - `resolvedBy` (string): Who accepted it.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `skontoTerms` (any): Cash discount terms.
- `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
- `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Gross total of the invoice.
- `totalAmountEur` (number): Gross total in EUR (ECB rate).
- `transactionNumber` (string): Internal number.
- `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
- `updatedAt` (string (date-time)): When the inbound invoice was last changed.
- `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
- `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
- `vendorName` (string): Name of the supplier as stated on the invoice.
- `vendorVatId` (string): Manual correction of the supplier's VAT ID.

Example 201 answer:

```json
{
  "createdAt": "2026-11-19T09:12:00Z",
  "customerNo": "99999",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b03",
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a03",
  "lineItems": [],
  "lockReasons": [],
  "processing": {
    "startedAt": "2026-11-19T09:12:00Z",
    "step": "queued"
  },
  "status": "RECEIVED",
  "tenantName": "DEMO",
  "transactionNumber": "ER-2026-00044",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-11-19T09:12:00Z",
  "validationStatus": "pending"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"dmsDocumentId":"9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b03"}'
```

## Get an inbound invoice (tenant:trade:inbound:read)

`GET /api/trade/v1/inbound-invoices/{id}`

Module: Trade · operationId: `getInboundInvoice` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

With extraction, lines, lock reasons, match result and OCR text.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Invoice (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
  - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
  - `extracted` (object): The supplier as read from the document.
  - `supplier` (object): The assigned master data supplier.
  - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
    - `cached` (boolean): The result came from the 24-hour cache of master data.
    - `checkedAt` (string (date-time)): When the VAT id was checked.
    - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
    - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
    - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
    - `statusDisplay` (string): The status as German text.
    - `statusMessage` (string): Message of the checking service, if any.
    - `vatId` (string): VAT id checked.
- `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
  - `eligible` (boolean): Every condition holds.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `reasons` (array of string): Each failed condition (German text).
  - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
  - `rule` (string): The rule that applied, also the protocol note of the release.
  - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
- `createdAt` (string (date-time)): When the inbound invoice was created.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string): Customer number of the tenant.
- `deliveryDate` (string (date)): Delivery date.
- `dmsDocumentId` (string (uuid)): DMS document of the invoice.
- `dueDate` (string (date)): Due date.
- `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
- `error` (string): Why processing failed (status `FAILED`).
- `exchangeRate` (number): Exchange rate to EUR.
- `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
  - `confidence` (object): Per field (AI extraction only).
  - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
  - `currency` (string): Currency (ISO 4217).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
  - `discountTerms` (array of object): Cash discount terms.
    - `days` (integer): Days within which the discount applies.
    - `percent` (number): Discount in percent.
  - `discountText` (string): Cash discount terms as printed.
  - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
  - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
  - `dueDate` (string): Due date (YYYY-MM-DD).
  - `grossTotal` (number): Gross total.
  - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
  - `invoiceNumber` (string): Invoice number.
  - `isReverseCharge` (boolean): The invoice is reverse charge.
  - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number): Net total.
  - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
  - `orderNumber` (string): Order number stated on the invoice.
  - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
  - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
  - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
  - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
  - `recipient` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
  - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
  - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
  - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `taxExemptionReason` (string): Stated reason for a tax exemption.
  - `taxRates` (array of object): Tax breakdown per rate.
    - `netAmount` (number): Net amount taxed at the rate.
    - `rate` (number): Tax rate in percent.
    - `taxAmount` (number): Tax amount at the rate.
  - `taxTotal` (number): Tax total.
  - `vendor` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text (single invoice only).
- `id` (string (uuid)): Id of the inbound invoice.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): The supplier's invoice number.
- `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
  - `articleAssignment` (object): How the article was resolved.
    - `confidence` (number): Confidence of the article assignment (0–1).
    - `evidence` (string): What the article assignment is based on.
    - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
  - `articleNumber` (string): Internal article number (masterdata).
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `ignored` (boolean): Article on the configured ignore list.
  - `mpn` (string): Manufacturer part number.
  - `netAmount` (number): Net amount of the line.
  - `orderLineRef` (string): Order line the line refers to (BT-132).
  - `orderNumber` (string): Order number the line refers to.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number.
- `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
  - `article` (string): Article of the line.
  - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
  - `description` (string): Human-readable explanation.
  - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
  - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
  - `variance` (number): Variance found (amount or quantity).
- `matchResult` (MatchResult)
  - `evaluatedAt` (string (date-time)): When the match ran.
  - `isBlocked` (boolean): A blocking lock reason was found.
  - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
  - `lockReasons` (array of LockReason): Lock reasons found.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchedLines` (array of object): Result per invoice line.
    - `articleNumber` (string): Article number in masterdata.
    - `availableQty` (number): Received minus already invoiced.
    - `description` (string): Description of the line.
    - `invoicePosition` (integer): Position on the invoice.
    - `invoicedPrice` (number): Unit price invoiced.
    - `invoicedQty` (number): Quantity invoiced.
    - `isMatched` (boolean): The line matches within the tolerances.
    - `poPosition` (integer): Position on the purchase order.
    - `poPrice` (number): Unit price ordered.
    - `poQty` (number): Quantity ordered.
    - `priceVariance` (number): Unit price variance.
    - `qtyVariance` (number): Quantity variance.
    - `receivedQty` (number): Quantity received.
    - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
  - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
  - `totalVariance` (number): Sum of the price variances.
- `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
- `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
- `netTotal` (number): Net total.
- `partnerReference` (string): Our order number as printed on the invoice.
- `paymentTermsText` (string): Payment terms as printed text.
- `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
  - `startedAt` (string (date-time)): When the current processing started.
  - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
- `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
- `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
  - `code` (string): Code of the lock reason.
  - `comment` (string): Why it was accepted.
  - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
  - `resolvedAt` (string (date-time)): When it was accepted.
  - `resolvedBy` (string): Who accepted it.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `skontoTerms` (any): Cash discount terms.
- `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
- `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Gross total of the invoice.
- `totalAmountEur` (number): Gross total in EUR (ECB rate).
- `transactionNumber` (string): Internal number.
- `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
- `updatedAt` (string (date-time)): When the inbound invoice was last changed.
- `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
- `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
- `vendorName` (string): Name of the supplier as stated on the invoice.
- `vendorVatId` (string): Manual correction of the supplier's VAT ID.

Example 200 answer:

```json
{
  "addressSnapshot": {
    "assignment": {
      "confidence": 1,
      "evidence": "USt-IdNr. DE701000001",
      "method": "exact_vat"
    },
    "extracted": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    },
    "supplier": {
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "name": "Nordlicht IT-Distribution GmbH",
      "supplierNumber": "70001"
    },
    "vatCheck": {
      "cached": false,
      "checkedAt": "2026-10-05T08:41:10Z",
      "method": "VIES",
      "serviceUnavailable": false,
      "status": "OFFICIALLY_CONFIRMED",
      "statusDisplay": "Gültig",
      "vatId": "DE701000001"
    }
  },
  "autoRelease": {
    "eligible": false,
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "mode": "dryRun",
    "reasons": [
      "Bruttobetrag 6.911,52 € liegt über der Grenze von 2.500,00 €."
    ],
    "released": false,
    "suppressed": false
  },
  "createdAt": "2026-10-05T08:40:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-10-01",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b01",
  "dueDate": "2026-11-01",
  "exchangeRate": 1,
  "extraction": {
    "currency": "EUR",
    "customerNumber": "K-99871",
    "deliveryDate": "2026-10-01",
    "documentType": "380",
    "documentTypeCode": "380",
    "dueDate": "2026-11-01",
    "grossTotal": 6911.52,
    "invoiceDate": "2026-10-02",
    "invoiceNumber": "RE-482117",
    "isReverseCharge": false,
    "lines": [
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1001",
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "ean": "4061234500014",
        "ignored": false,
        "netAmount": 4974,
        "orderNumber": "BE-2026-00058",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 829,
        "vendorArticleNo": "NL-PB14G10-16"
      },
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-DOCKC100",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1004",
        "description": "USB-C Dockingstation 100 W",
        "ean": "4061234500045",
        "ignored": false,
        "netAmount": 834,
        "orderNumber": "BE-2026-00058",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 139,
        "vendorArticleNo": "NL-DOCKC100"
      }
    ],
    "netDays": 30,
    "netTotal": 5808,
    "orderNumber": "BE-2026-00058",
    "paymentMeansCode": "58",
    "paymentMeansText": "SEPA-Überweisung",
    "paymentText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
    "recipient": {
      "city": "Regensburg",
      "country": "DE",
      "name": "Muster IT-Systemhaus GmbH",
      "street": "Industriestraße 12",
      "vatId": "DE999000111",
      "zip": "93055"
    },
    "sourceKind": "XRECHNUNG_CII",
    "taxRates": [
      {
        "netAmount": 5808,
        "rate": 19,
        "taxAmount": 1103.52
      }
    ],
    "taxTotal": 1103.52,
    "vendor": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    }
  },
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a01",
  "invoiceDate": "2026-10-02",
  "invoiceNumber": "RE-482117",
  "lineItems": [
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1001",
      "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
      "ean": "4061234500014",
      "ignored": false,
      "netAmount": 4974,
      "orderNumber": "BE-2026-00058",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 829,
      "vendorArticleNo": "NL-PB14G10-16"
    },
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-DOCKC100",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1004",
      "description": "USB-C Dockingstation 100 W",
      "ean": "4061234500045",
      "ignored": false,
      "netAmount": 834,
      "orderNumber": "BE-2026-00058",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 139,
      "vendorArticleNo": "NL-DOCKC100"
    }
  ],
  "lockReasons": [],
  "matchResult": {
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "isBlocked": false,
    "isMatched": true,
    "lockReasons": [],
    "matchedLines": [
      {
        "articleNumber": "HW-1001",
        "availableQty": 6,
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "invoicePosition": 1,
        "invoicedPrice": 829,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 1,
        "poPrice": 829,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      },
      {
        "articleNumber": "HW-1004",
        "availableQty": 6,
        "description": "USB-C Dockingstation 100 W",
        "invoicePosition": 2,
        "invoicedPrice": 139,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 2,
        "poPrice": 139,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      }
    ],
    "status": "matched",
    "totalVariance": 0
  },
  "matchingStatus": "matched",
  "netDays": 30,
  "netTotal": 5808,
  "partnerReference": "BE-2026-00058",
  "paymentTermsText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d58",
  "sourceKind": "XRECHNUNG_CII",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "taxTotal": 1103.52,
  "tenantName": "DEMO",
  "totalAmount": 6911.52,
  "totalAmountEur": 6911.52,
  "transactionNumber": "ER-2026-00031",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-10-05T08:41:12Z",
  "validationReport": {
    "findings": [],
    "scenario": "EN16931 XRechnung (CII)",
    "syntax": "CII",
    "valid": true
  },
  "validationStatus": "valid",
  "vendorName": "Nordlicht IT-Distribution GmbH"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Correct an inbound invoice during review (tenant:trade:inbound:write)

`PATCH /api/trade/v1/inbound-invoices/{id}`

Module: Trade · operationId: `updateInboundInvoice` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

Allowed in `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW` and `DUPLICATE`. Only fields sent are
changed; `lines` replaces all lines. The invoice is validated and matched again. The extraction
(what was read) is never changed.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `currency` (string): Currency (ISO 4217).
- `dueDate` (string (date)): Due date.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): Invoice number. (max length 100)
- `lines` (array of object): Lines; replace all lines when present.
  - `position` (integer, required): Position number of the line.
  - `articleNumber` (string): Article number in masterdata. (max length 100)
  - `description` (string): Description of the line. (max length 500)
  - `ean` (string): EAN (GTIN) of the article. (max length 32)
  - `mpn` (string): Manufacturer part number. (max length 100)
  - `netAmount` (number): Net amount of the line.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent. (max 100)
  - `unit` (string): Unit of measure. (max length 20)
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number. (max length 100)
- `netTotal` (number): Net total.
- `note` (string): Recorded with the change. (max length 1000)
- `orderNumber` (string): Order number stated on the invoice. (max length 100)
- `purchaseOrderId` (string (uuid)): Purchase order to match the invoice against.
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `totalAmount` (number): Gross total of the invoice.
- `vendorName` (string): Name of the supplier. (max length 300)
- `vendorVatId` (string): VAT id of the supplier. (max length 32)

Example:

```json
{
  "note": "Lieferant manuell zugeordnet.",
  "orderNumber": "BE-2026-0815",
  "supplierAddressId": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f"
}
```

### Responses

- **200** Updated invoice (`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 current state does not allow the action (`code` `invalid_state` or `blocked`). (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
  - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
  - `extracted` (object): The supplier as read from the document.
  - `supplier` (object): The assigned master data supplier.
  - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
    - `cached` (boolean): The result came from the 24-hour cache of master data.
    - `checkedAt` (string (date-time)): When the VAT id was checked.
    - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
    - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
    - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
    - `statusDisplay` (string): The status as German text.
    - `statusMessage` (string): Message of the checking service, if any.
    - `vatId` (string): VAT id checked.
- `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
  - `eligible` (boolean): Every condition holds.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `reasons` (array of string): Each failed condition (German text).
  - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
  - `rule` (string): The rule that applied, also the protocol note of the release.
  - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
- `createdAt` (string (date-time)): When the inbound invoice was created.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string): Customer number of the tenant.
- `deliveryDate` (string (date)): Delivery date.
- `dmsDocumentId` (string (uuid)): DMS document of the invoice.
- `dueDate` (string (date)): Due date.
- `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
- `error` (string): Why processing failed (status `FAILED`).
- `exchangeRate` (number): Exchange rate to EUR.
- `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
  - `confidence` (object): Per field (AI extraction only).
  - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
  - `currency` (string): Currency (ISO 4217).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
  - `discountTerms` (array of object): Cash discount terms.
    - `days` (integer): Days within which the discount applies.
    - `percent` (number): Discount in percent.
  - `discountText` (string): Cash discount terms as printed.
  - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
  - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
  - `dueDate` (string): Due date (YYYY-MM-DD).
  - `grossTotal` (number): Gross total.
  - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
  - `invoiceNumber` (string): Invoice number.
  - `isReverseCharge` (boolean): The invoice is reverse charge.
  - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number): Net total.
  - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
  - `orderNumber` (string): Order number stated on the invoice.
  - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
  - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
  - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
  - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
  - `recipient` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
  - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
  - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
  - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `taxExemptionReason` (string): Stated reason for a tax exemption.
  - `taxRates` (array of object): Tax breakdown per rate.
    - `netAmount` (number): Net amount taxed at the rate.
    - `rate` (number): Tax rate in percent.
    - `taxAmount` (number): Tax amount at the rate.
  - `taxTotal` (number): Tax total.
  - `vendor` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text (single invoice only).
- `id` (string (uuid)): Id of the inbound invoice.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): The supplier's invoice number.
- `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
  - `articleAssignment` (object): How the article was resolved.
    - `confidence` (number): Confidence of the article assignment (0–1).
    - `evidence` (string): What the article assignment is based on.
    - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
  - `articleNumber` (string): Internal article number (masterdata).
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `ignored` (boolean): Article on the configured ignore list.
  - `mpn` (string): Manufacturer part number.
  - `netAmount` (number): Net amount of the line.
  - `orderLineRef` (string): Order line the line refers to (BT-132).
  - `orderNumber` (string): Order number the line refers to.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number.
- `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
  - `article` (string): Article of the line.
  - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
  - `description` (string): Human-readable explanation.
  - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
  - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
  - `variance` (number): Variance found (amount or quantity).
- `matchResult` (MatchResult)
  - `evaluatedAt` (string (date-time)): When the match ran.
  - `isBlocked` (boolean): A blocking lock reason was found.
  - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
  - `lockReasons` (array of LockReason): Lock reasons found.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchedLines` (array of object): Result per invoice line.
    - `articleNumber` (string): Article number in masterdata.
    - `availableQty` (number): Received minus already invoiced.
    - `description` (string): Description of the line.
    - `invoicePosition` (integer): Position on the invoice.
    - `invoicedPrice` (number): Unit price invoiced.
    - `invoicedQty` (number): Quantity invoiced.
    - `isMatched` (boolean): The line matches within the tolerances.
    - `poPosition` (integer): Position on the purchase order.
    - `poPrice` (number): Unit price ordered.
    - `poQty` (number): Quantity ordered.
    - `priceVariance` (number): Unit price variance.
    - `qtyVariance` (number): Quantity variance.
    - `receivedQty` (number): Quantity received.
    - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
  - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
  - `totalVariance` (number): Sum of the price variances.
- `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
- `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
- `netTotal` (number): Net total.
- `partnerReference` (string): Our order number as printed on the invoice.
- `paymentTermsText` (string): Payment terms as printed text.
- `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
  - `startedAt` (string (date-time)): When the current processing started.
  - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
- `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
- `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
  - `code` (string): Code of the lock reason.
  - `comment` (string): Why it was accepted.
  - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
  - `resolvedAt` (string (date-time)): When it was accepted.
  - `resolvedBy` (string): Who accepted it.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `skontoTerms` (any): Cash discount terms.
- `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
- `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Gross total of the invoice.
- `totalAmountEur` (number): Gross total in EUR (ECB rate).
- `transactionNumber` (string): Internal number.
- `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
- `updatedAt` (string (date-time)): When the inbound invoice was last changed.
- `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
- `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
- `vendorName` (string): Name of the supplier as stated on the invoice.
- `vendorVatId` (string): Manual correction of the supplier's VAT ID.

Example 200 answer:

```json
{
  "addressSnapshot": {
    "assignment": {
      "confidence": 1,
      "evidence": "USt-IdNr. DE701000001",
      "method": "exact_vat"
    },
    "extracted": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    },
    "supplier": {
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "name": "Nordlicht IT-Distribution GmbH",
      "supplierNumber": "70001"
    },
    "vatCheck": {
      "cached": false,
      "checkedAt": "2026-10-05T08:41:10Z",
      "method": "VIES",
      "serviceUnavailable": false,
      "status": "OFFICIALLY_CONFIRMED",
      "statusDisplay": "Gültig",
      "vatId": "DE701000001"
    }
  },
  "autoRelease": {
    "eligible": false,
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "mode": "dryRun",
    "reasons": [
      "Bruttobetrag 6.911,52 € liegt über der Grenze von 2.500,00 €."
    ],
    "released": false,
    "suppressed": false
  },
  "createdAt": "2026-10-05T08:40:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-10-01",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b01",
  "dueDate": "2026-11-01",
  "exchangeRate": 1,
  "extraction": {
    "currency": "EUR",
    "customerNumber": "K-99871",
    "deliveryDate": "2026-10-01",
    "documentType": "380",
    "documentTypeCode": "380",
    "dueDate": "2026-11-01",
    "grossTotal": 6911.52,
    "invoiceDate": "2026-10-02",
    "invoiceNumber": "RE-482117",
    "isReverseCharge": false,
    "lines": [
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1001",
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "ean": "4061234500014",
        "ignored": false,
        "netAmount": 4974,
        "orderNumber": "BE-2026-00058",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 829,
        "vendorArticleNo": "NL-PB14G10-16"
      },
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-DOCKC100",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1004",
        "description": "USB-C Dockingstation 100 W",
        "ean": "4061234500045",
        "ignored": false,
        "netAmount": 834,
        "orderNumber": "BE-2026-00058",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 139,
        "vendorArticleNo": "NL-DOCKC100"
      }
    ],
    "netDays": 30,
    "netTotal": 5808,
    "orderNumber": "BE-2026-00058",
    "paymentMeansCode": "58",
    "paymentMeansText": "SEPA-Überweisung",
    "paymentText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
    "recipient": {
      "city": "Regensburg",
      "country": "DE",
      "name": "Muster IT-Systemhaus GmbH",
      "street": "Industriestraße 12",
      "vatId": "DE999000111",
      "zip": "93055"
    },
    "sourceKind": "XRECHNUNG_CII",
    "taxRates": [
      {
        "netAmount": 5808,
        "rate": 19,
        "taxAmount": 1103.52
      }
    ],
    "taxTotal": 1103.52,
    "vendor": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    }
  },
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a01",
  "invoiceDate": "2026-10-02",
  "invoiceNumber": "RE-482117",
  "lineItems": [
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1001",
      "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
      "ean": "4061234500014",
      "ignored": false,
      "netAmount": 4974,
      "orderNumber": "BE-2026-00058",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 829,
      "vendorArticleNo": "NL-PB14G10-16"
    },
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-DOCKC100",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1004",
      "description": "USB-C Dockingstation 100 W",
      "ean": "4061234500045",
      "ignored": false,
      "netAmount": 834,
      "orderNumber": "BE-2026-00058",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 139,
      "vendorArticleNo": "NL-DOCKC100"
    }
  ],
  "lockReasons": [],
  "matchResult": {
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "isBlocked": false,
    "isMatched": true,
    "lockReasons": [],
    "matchedLines": [
      {
        "articleNumber": "HW-1001",
        "availableQty": 6,
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "invoicePosition": 1,
        "invoicedPrice": 829,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 1,
        "poPrice": 829,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      },
      {
        "articleNumber": "HW-1004",
        "availableQty": 6,
        "description": "USB-C Dockingstation 100 W",
        "invoicePosition": 2,
        "invoicedPrice": 139,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 2,
        "poPrice": 139,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      }
    ],
    "status": "matched",
    "totalVariance": 0
  },
  "matchingStatus": "matched",
  "netDays": 30,
  "netTotal": 5808,
  "partnerReference": "BE-2026-00058",
  "paymentTermsText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d58",
  "sourceKind": "XRECHNUNG_CII",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "taxTotal": 1103.52,
  "tenantName": "DEMO",
  "totalAmount": 6911.52,
  "totalAmountEur": 6911.52,
  "transactionNumber": "ER-2026-00031",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-10-05T08:41:12Z",
  "validationReport": {
    "findings": [],
    "scenario": "EN16931 XRechnung (CII)",
    "syntax": "CII",
    "valid": true
  },
  "validationStatus": "valid",
  "vendorName": "Nordlicht IT-Distribution GmbH"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"note":"Lieferant manuell zugeordnet.","orderNumber":"BE-2026-0815","supplierAddressId":"7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f"}'
```

## Download the invoice document (tenant:trade:inbound:read)

`GET /api/trade/v1/inbound-invoices/{id}/document`

Module: Trade · operationId: `getInboundInvoiceDocument` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

Streams the DMS file of the invoice with its `Content-Type`, `Content-Disposition` and `ETag`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The file (`application/octet-stream`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/document' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Match an inbound invoice again (tenant:trade:inbound:write)

`POST /api/trade/v1/inbound-invoices/{id}/match`

Module: Trade · operationId: `matchInboundInvoice` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

Re-runs the purchase order check, optionally against a given purchase order (id or number). Allowed in the same statuses as corrections. The body is optional.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `purchaseOrderId` (string (uuid))
- `purchaseOrderNumber` (string): (max length 64)

Example:

```json
{
  "purchaseOrderNumber": "BE-2026-00058"
}
```

### Responses

- **200** Matched invoice (`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 current state does not allow the action (`code` `invalid_state` or `blocked`). (`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 200 answer:

- `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
  - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
  - `extracted` (object): The supplier as read from the document.
  - `supplier` (object): The assigned master data supplier.
  - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
    - `cached` (boolean): The result came from the 24-hour cache of master data.
    - `checkedAt` (string (date-time)): When the VAT id was checked.
    - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
    - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
    - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
    - `statusDisplay` (string): The status as German text.
    - `statusMessage` (string): Message of the checking service, if any.
    - `vatId` (string): VAT id checked.
- `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
  - `eligible` (boolean): Every condition holds.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `reasons` (array of string): Each failed condition (German text).
  - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
  - `rule` (string): The rule that applied, also the protocol note of the release.
  - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
- `createdAt` (string (date-time)): When the inbound invoice was created.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string): Customer number of the tenant.
- `deliveryDate` (string (date)): Delivery date.
- `dmsDocumentId` (string (uuid)): DMS document of the invoice.
- `dueDate` (string (date)): Due date.
- `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
- `error` (string): Why processing failed (status `FAILED`).
- `exchangeRate` (number): Exchange rate to EUR.
- `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
  - `confidence` (object): Per field (AI extraction only).
  - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
  - `currency` (string): Currency (ISO 4217).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
  - `discountTerms` (array of object): Cash discount terms.
    - `days` (integer): Days within which the discount applies.
    - `percent` (number): Discount in percent.
  - `discountText` (string): Cash discount terms as printed.
  - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
  - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
  - `dueDate` (string): Due date (YYYY-MM-DD).
  - `grossTotal` (number): Gross total.
  - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
  - `invoiceNumber` (string): Invoice number.
  - `isReverseCharge` (boolean): The invoice is reverse charge.
  - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number): Net total.
  - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
  - `orderNumber` (string): Order number stated on the invoice.
  - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
  - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
  - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
  - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
  - `recipient` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
  - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
  - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
  - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `taxExemptionReason` (string): Stated reason for a tax exemption.
  - `taxRates` (array of object): Tax breakdown per rate.
    - `netAmount` (number): Net amount taxed at the rate.
    - `rate` (number): Tax rate in percent.
    - `taxAmount` (number): Tax amount at the rate.
  - `taxTotal` (number): Tax total.
  - `vendor` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text (single invoice only).
- `id` (string (uuid)): Id of the inbound invoice.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): The supplier's invoice number.
- `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
  - `articleAssignment` (object): How the article was resolved.
    - `confidence` (number): Confidence of the article assignment (0–1).
    - `evidence` (string): What the article assignment is based on.
    - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
  - `articleNumber` (string): Internal article number (masterdata).
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `ignored` (boolean): Article on the configured ignore list.
  - `mpn` (string): Manufacturer part number.
  - `netAmount` (number): Net amount of the line.
  - `orderLineRef` (string): Order line the line refers to (BT-132).
  - `orderNumber` (string): Order number the line refers to.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number.
- `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
  - `article` (string): Article of the line.
  - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
  - `description` (string): Human-readable explanation.
  - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
  - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
  - `variance` (number): Variance found (amount or quantity).
- `matchResult` (MatchResult)
  - `evaluatedAt` (string (date-time)): When the match ran.
  - `isBlocked` (boolean): A blocking lock reason was found.
  - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
  - `lockReasons` (array of LockReason): Lock reasons found.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchedLines` (array of object): Result per invoice line.
    - `articleNumber` (string): Article number in masterdata.
    - `availableQty` (number): Received minus already invoiced.
    - `description` (string): Description of the line.
    - `invoicePosition` (integer): Position on the invoice.
    - `invoicedPrice` (number): Unit price invoiced.
    - `invoicedQty` (number): Quantity invoiced.
    - `isMatched` (boolean): The line matches within the tolerances.
    - `poPosition` (integer): Position on the purchase order.
    - `poPrice` (number): Unit price ordered.
    - `poQty` (number): Quantity ordered.
    - `priceVariance` (number): Unit price variance.
    - `qtyVariance` (number): Quantity variance.
    - `receivedQty` (number): Quantity received.
    - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
  - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
  - `totalVariance` (number): Sum of the price variances.
- `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
- `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
- `netTotal` (number): Net total.
- `partnerReference` (string): Our order number as printed on the invoice.
- `paymentTermsText` (string): Payment terms as printed text.
- `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
  - `startedAt` (string (date-time)): When the current processing started.
  - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
- `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
- `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
  - `code` (string): Code of the lock reason.
  - `comment` (string): Why it was accepted.
  - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
  - `resolvedAt` (string (date-time)): When it was accepted.
  - `resolvedBy` (string): Who accepted it.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `skontoTerms` (any): Cash discount terms.
- `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
- `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Gross total of the invoice.
- `totalAmountEur` (number): Gross total in EUR (ECB rate).
- `transactionNumber` (string): Internal number.
- `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
- `updatedAt` (string (date-time)): When the inbound invoice was last changed.
- `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
- `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
- `vendorName` (string): Name of the supplier as stated on the invoice.
- `vendorVatId` (string): Manual correction of the supplier's VAT ID.

Example 200 answer:

```json
{
  "addressSnapshot": {
    "assignment": {
      "confidence": 1,
      "evidence": "USt-IdNr. DE701000001",
      "method": "exact_vat"
    },
    "extracted": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    },
    "supplier": {
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "name": "Nordlicht IT-Distribution GmbH",
      "supplierNumber": "70001"
    },
    "vatCheck": {
      "cached": false,
      "checkedAt": "2026-10-05T08:41:10Z",
      "method": "VIES",
      "serviceUnavailable": false,
      "status": "OFFICIALLY_CONFIRMED",
      "statusDisplay": "Gültig",
      "vatId": "DE701000001"
    }
  },
  "autoRelease": {
    "eligible": false,
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "mode": "dryRun",
    "reasons": [
      "Bruttobetrag 6.911,52 € liegt über der Grenze von 2.500,00 €."
    ],
    "released": false,
    "suppressed": false
  },
  "createdAt": "2026-10-05T08:40:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-10-01",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b01",
  "dueDate": "2026-11-01",
  "exchangeRate": 1,
  "extraction": {
    "currency": "EUR",
    "customerNumber": "K-99871",
    "deliveryDate": "2026-10-01",
    "documentType": "380",
    "documentTypeCode": "380",
    "dueDate": "2026-11-01",
    "grossTotal": 6911.52,
    "invoiceDate": "2026-10-02",
    "invoiceNumber": "RE-482117",
    "isReverseCharge": false,
    "lines": [
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1001",
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "ean": "4061234500014",
        "ignored": false,
        "netAmount": 4974,
        "orderNumber": "BE-2026-00058",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 829,
        "vendorArticleNo": "NL-PB14G10-16"
      },
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-DOCKC100",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1004",
        "description": "USB-C Dockingstation 100 W",
        "ean": "4061234500045",
        "ignored": false,
        "netAmount": 834,
        "orderNumber": "BE-2026-00058",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 139,
        "vendorArticleNo": "NL-DOCKC100"
      }
    ],
    "netDays": 30,
    "netTotal": 5808,
    "orderNumber": "BE-2026-00058",
    "paymentMeansCode": "58",
    "paymentMeansText": "SEPA-Überweisung",
    "paymentText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
    "recipient": {
      "city": "Regensburg",
      "country": "DE",
      "name": "Muster IT-Systemhaus GmbH",
      "street": "Industriestraße 12",
      "vatId": "DE999000111",
      "zip": "93055"
    },
    "sourceKind": "XRECHNUNG_CII",
    "taxRates": [
      {
        "netAmount": 5808,
        "rate": 19,
        "taxAmount": 1103.52
      }
    ],
    "taxTotal": 1103.52,
    "vendor": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    }
  },
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a01",
  "invoiceDate": "2026-10-02",
  "invoiceNumber": "RE-482117",
  "lineItems": [
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1001",
      "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
      "ean": "4061234500014",
      "ignored": false,
      "netAmount": 4974,
      "orderNumber": "BE-2026-00058",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 829,
      "vendorArticleNo": "NL-PB14G10-16"
    },
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-DOCKC100",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1004",
      "description": "USB-C Dockingstation 100 W",
      "ean": "4061234500045",
      "ignored": false,
      "netAmount": 834,
      "orderNumber": "BE-2026-00058",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 139,
      "vendorArticleNo": "NL-DOCKC100"
    }
  ],
  "lockReasons": [],
  "matchResult": {
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "isBlocked": false,
    "isMatched": true,
    "lockReasons": [],
    "matchedLines": [
      {
        "articleNumber": "HW-1001",
        "availableQty": 6,
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "invoicePosition": 1,
        "invoicedPrice": 829,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 1,
        "poPrice": 829,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      },
      {
        "articleNumber": "HW-1004",
        "availableQty": 6,
        "description": "USB-C Dockingstation 100 W",
        "invoicePosition": 2,
        "invoicedPrice": 139,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 2,
        "poPrice": 139,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      }
    ],
    "status": "matched",
    "totalVariance": 0
  },
  "matchingStatus": "matched",
  "netDays": 30,
  "netTotal": 5808,
  "partnerReference": "BE-2026-00058",
  "paymentTermsText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d58",
  "sourceKind": "XRECHNUNG_CII",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "taxTotal": 1103.52,
  "tenantName": "DEMO",
  "totalAmount": 6911.52,
  "totalAmountEur": 6911.52,
  "transactionNumber": "ER-2026-00031",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-10-05T08:41:12Z",
  "validationReport": {
    "findings": [],
    "scenario": "EN16931 XRechnung (CII)",
    "syntax": "CII",
    "valid": true
  },
  "validationStatus": "valid",
  "vendorName": "Nordlicht IT-Distribution GmbH"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/match' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"purchaseOrderNumber":"BE-2026-00058"}'
```

## Release an inbound invoice (tenant:trade:inbound:approve)

`POST /api/trade/v1/inbound-invoices/{id}/release`

Module: Trade · operationId: `releaseInboundInvoice` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

`MATCHED`, `DISCREPANCY` or `IN_REVIEW` → `RELEASED`; publishes `trade.inboundinvoice.released`.
An invoice with blocking lock reasons needs `override: true` and a `comment` (`409 blocked` otherwise).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `comment` (string): (max length 2000)
- `override` (boolean): Release despite blocking lock reasons (needs a comment).
- `reason` (string): Legacy name of `comment` (reject). (max length 2000)

Example:

```json
{
  "comment": "Preisabweichung mit Lieferant geklärt.",
  "override": true
}
```

### Responses

- **200** Released invoice (`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 current state does not allow the action (`code` `invalid_state` or `blocked`). (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
  - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
  - `extracted` (object): The supplier as read from the document.
  - `supplier` (object): The assigned master data supplier.
  - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
    - `cached` (boolean): The result came from the 24-hour cache of master data.
    - `checkedAt` (string (date-time)): When the VAT id was checked.
    - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
    - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
    - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
    - `statusDisplay` (string): The status as German text.
    - `statusMessage` (string): Message of the checking service, if any.
    - `vatId` (string): VAT id checked.
- `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
  - `eligible` (boolean): Every condition holds.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `reasons` (array of string): Each failed condition (German text).
  - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
  - `rule` (string): The rule that applied, also the protocol note of the release.
  - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
- `createdAt` (string (date-time)): When the inbound invoice was created.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string): Customer number of the tenant.
- `deliveryDate` (string (date)): Delivery date.
- `dmsDocumentId` (string (uuid)): DMS document of the invoice.
- `dueDate` (string (date)): Due date.
- `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
- `error` (string): Why processing failed (status `FAILED`).
- `exchangeRate` (number): Exchange rate to EUR.
- `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
  - `confidence` (object): Per field (AI extraction only).
  - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
  - `currency` (string): Currency (ISO 4217).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
  - `discountTerms` (array of object): Cash discount terms.
    - `days` (integer): Days within which the discount applies.
    - `percent` (number): Discount in percent.
  - `discountText` (string): Cash discount terms as printed.
  - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
  - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
  - `dueDate` (string): Due date (YYYY-MM-DD).
  - `grossTotal` (number): Gross total.
  - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
  - `invoiceNumber` (string): Invoice number.
  - `isReverseCharge` (boolean): The invoice is reverse charge.
  - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number): Net total.
  - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
  - `orderNumber` (string): Order number stated on the invoice.
  - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
  - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
  - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
  - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
  - `recipient` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
  - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
  - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
  - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `taxExemptionReason` (string): Stated reason for a tax exemption.
  - `taxRates` (array of object): Tax breakdown per rate.
    - `netAmount` (number): Net amount taxed at the rate.
    - `rate` (number): Tax rate in percent.
    - `taxAmount` (number): Tax amount at the rate.
  - `taxTotal` (number): Tax total.
  - `vendor` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text (single invoice only).
- `id` (string (uuid)): Id of the inbound invoice.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): The supplier's invoice number.
- `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
  - `articleAssignment` (object): How the article was resolved.
    - `confidence` (number): Confidence of the article assignment (0–1).
    - `evidence` (string): What the article assignment is based on.
    - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
  - `articleNumber` (string): Internal article number (masterdata).
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `ignored` (boolean): Article on the configured ignore list.
  - `mpn` (string): Manufacturer part number.
  - `netAmount` (number): Net amount of the line.
  - `orderLineRef` (string): Order line the line refers to (BT-132).
  - `orderNumber` (string): Order number the line refers to.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number.
- `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
  - `article` (string): Article of the line.
  - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
  - `description` (string): Human-readable explanation.
  - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
  - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
  - `variance` (number): Variance found (amount or quantity).
- `matchResult` (MatchResult)
  - `evaluatedAt` (string (date-time)): When the match ran.
  - `isBlocked` (boolean): A blocking lock reason was found.
  - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
  - `lockReasons` (array of LockReason): Lock reasons found.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchedLines` (array of object): Result per invoice line.
    - `articleNumber` (string): Article number in masterdata.
    - `availableQty` (number): Received minus already invoiced.
    - `description` (string): Description of the line.
    - `invoicePosition` (integer): Position on the invoice.
    - `invoicedPrice` (number): Unit price invoiced.
    - `invoicedQty` (number): Quantity invoiced.
    - `isMatched` (boolean): The line matches within the tolerances.
    - `poPosition` (integer): Position on the purchase order.
    - `poPrice` (number): Unit price ordered.
    - `poQty` (number): Quantity ordered.
    - `priceVariance` (number): Unit price variance.
    - `qtyVariance` (number): Quantity variance.
    - `receivedQty` (number): Quantity received.
    - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
  - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
  - `totalVariance` (number): Sum of the price variances.
- `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
- `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
- `netTotal` (number): Net total.
- `partnerReference` (string): Our order number as printed on the invoice.
- `paymentTermsText` (string): Payment terms as printed text.
- `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
  - `startedAt` (string (date-time)): When the current processing started.
  - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
- `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
- `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
  - `code` (string): Code of the lock reason.
  - `comment` (string): Why it was accepted.
  - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
  - `resolvedAt` (string (date-time)): When it was accepted.
  - `resolvedBy` (string): Who accepted it.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `skontoTerms` (any): Cash discount terms.
- `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
- `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Gross total of the invoice.
- `totalAmountEur` (number): Gross total in EUR (ECB rate).
- `transactionNumber` (string): Internal number.
- `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
- `updatedAt` (string (date-time)): When the inbound invoice was last changed.
- `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
- `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
- `vendorName` (string): Name of the supplier as stated on the invoice.
- `vendorVatId` (string): Manual correction of the supplier's VAT ID.

Example 200 answer:

```json
{
  "addressSnapshot": {
    "assignment": {
      "confidence": 1,
      "evidence": "USt-IdNr. DE701000001",
      "method": "exact_vat"
    },
    "extracted": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    },
    "supplier": {
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "name": "Nordlicht IT-Distribution GmbH",
      "supplierNumber": "70001"
    },
    "vatCheck": {
      "cached": false,
      "checkedAt": "2026-10-05T08:41:10Z",
      "method": "VIES",
      "serviceUnavailable": false,
      "status": "OFFICIALLY_CONFIRMED",
      "statusDisplay": "Gültig",
      "vatId": "DE701000001"
    }
  },
  "createdAt": "2026-10-05T08:40:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-10-01",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b01",
  "dueDate": "2026-11-01",
  "exchangeRate": 1,
  "extraction": {
    "currency": "EUR",
    "customerNumber": "K-99871",
    "deliveryDate": "2026-10-01",
    "documentType": "380",
    "documentTypeCode": "380",
    "dueDate": "2026-11-01",
    "grossTotal": 6911.52,
    "invoiceDate": "2026-10-02",
    "invoiceNumber": "RE-482117",
    "isReverseCharge": false,
    "lines": [
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1001",
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "ean": "4061234500014",
        "ignored": false,
        "netAmount": 4974,
        "orderNumber": "BE-2026-00058",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 829,
        "vendorArticleNo": "NL-PB14G10-16"
      },
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-DOCKC100",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1004",
        "description": "USB-C Dockingstation 100 W",
        "ean": "4061234500045",
        "ignored": false,
        "netAmount": 834,
        "orderNumber": "BE-2026-00058",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 139,
        "vendorArticleNo": "NL-DOCKC100"
      }
    ],
    "netDays": 30,
    "netTotal": 5808,
    "orderNumber": "BE-2026-00058",
    "paymentMeansCode": "58",
    "paymentMeansText": "SEPA-Überweisung",
    "paymentText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
    "recipient": {
      "city": "Regensburg",
      "country": "DE",
      "name": "Muster IT-Systemhaus GmbH",
      "street": "Industriestraße 12",
      "vatId": "DE999000111",
      "zip": "93055"
    },
    "sourceKind": "XRECHNUNG_CII",
    "taxRates": [
      {
        "netAmount": 5808,
        "rate": 19,
        "taxAmount": 1103.52
      }
    ],
    "taxTotal": 1103.52,
    "vendor": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    }
  },
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a01",
  "invoiceDate": "2026-10-02",
  "invoiceNumber": "RE-482117",
  "lineItems": [
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1001",
      "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
      "ean": "4061234500014",
      "ignored": false,
      "netAmount": 4974,
      "orderNumber": "BE-2026-00058",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 829,
      "vendorArticleNo": "NL-PB14G10-16"
    },
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-DOCKC100",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1004",
      "description": "USB-C Dockingstation 100 W",
      "ean": "4061234500045",
      "ignored": false,
      "netAmount": 834,
      "orderNumber": "BE-2026-00058",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 139,
      "vendorArticleNo": "NL-DOCKC100"
    }
  ],
  "lockReasons": [],
  "matchResult": {
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "isBlocked": false,
    "isMatched": true,
    "lockReasons": [],
    "matchedLines": [
      {
        "articleNumber": "HW-1001",
        "availableQty": 6,
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "invoicePosition": 1,
        "invoicedPrice": 829,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 1,
        "poPrice": 829,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      },
      {
        "articleNumber": "HW-1004",
        "availableQty": 6,
        "description": "USB-C Dockingstation 100 W",
        "invoicePosition": 2,
        "invoicedPrice": 139,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 2,
        "poPrice": 139,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      }
    ],
    "status": "matched",
    "totalVariance": 0
  },
  "matchingStatus": "matched",
  "netDays": 30,
  "netTotal": 5808,
  "partnerReference": "BE-2026-00058",
  "paymentTermsText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d58",
  "sourceKind": "XRECHNUNG_CII",
  "status": "RELEASED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "taxTotal": 1103.52,
  "tenantName": "DEMO",
  "totalAmount": 6911.52,
  "totalAmountEur": 6911.52,
  "transactionNumber": "ER-2026-00031",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-10-06T07:55:00Z",
  "validationReport": {
    "findings": [],
    "scenario": "EN16931 XRechnung (CII)",
    "syntax": "CII",
    "valid": true
  },
  "validationStatus": "valid",
  "vendorName": "Nordlicht IT-Distribution GmbH"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/release' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"comment":"Preisabweichung mit Lieferant geklärt.","override":true}'
```

## Reject an inbound invoice (tenant:trade:inbound:approve)

`POST /api/trade/v1/inbound-invoices/{id}/reject`

Module: Trade · operationId: `rejectInboundInvoice` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

Any status except `RELEASED` and `REJECTED` → `REJECTED`. A `comment` (or the legacy `reason`) is required (`422` otherwise).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `comment` (string): (max length 2000)
- `override` (boolean): Release despite blocking lock reasons (needs a comment).
- `reason` (string): Legacy name of `comment` (reject). (max length 2000)

Example:

```json
{
  "comment": "Preisabweichung mit Lieferant geklärt.",
  "override": true
}
```

### Responses

- **200** Rejected invoice (`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 current state does not allow the action (`code` `invalid_state` or `blocked`). (`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 200 answer:

- `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
  - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
  - `extracted` (object): The supplier as read from the document.
  - `supplier` (object): The assigned master data supplier.
  - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
    - `cached` (boolean): The result came from the 24-hour cache of master data.
    - `checkedAt` (string (date-time)): When the VAT id was checked.
    - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
    - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
    - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
    - `statusDisplay` (string): The status as German text.
    - `statusMessage` (string): Message of the checking service, if any.
    - `vatId` (string): VAT id checked.
- `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
  - `eligible` (boolean): Every condition holds.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `reasons` (array of string): Each failed condition (German text).
  - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
  - `rule` (string): The rule that applied, also the protocol note of the release.
  - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
- `createdAt` (string (date-time)): When the inbound invoice was created.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string): Customer number of the tenant.
- `deliveryDate` (string (date)): Delivery date.
- `dmsDocumentId` (string (uuid)): DMS document of the invoice.
- `dueDate` (string (date)): Due date.
- `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
- `error` (string): Why processing failed (status `FAILED`).
- `exchangeRate` (number): Exchange rate to EUR.
- `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
  - `confidence` (object): Per field (AI extraction only).
  - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
  - `currency` (string): Currency (ISO 4217).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
  - `discountTerms` (array of object): Cash discount terms.
    - `days` (integer): Days within which the discount applies.
    - `percent` (number): Discount in percent.
  - `discountText` (string): Cash discount terms as printed.
  - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
  - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
  - `dueDate` (string): Due date (YYYY-MM-DD).
  - `grossTotal` (number): Gross total.
  - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
  - `invoiceNumber` (string): Invoice number.
  - `isReverseCharge` (boolean): The invoice is reverse charge.
  - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number): Net total.
  - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
  - `orderNumber` (string): Order number stated on the invoice.
  - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
  - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
  - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
  - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
  - `recipient` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
  - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
  - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
  - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `taxExemptionReason` (string): Stated reason for a tax exemption.
  - `taxRates` (array of object): Tax breakdown per rate.
    - `netAmount` (number): Net amount taxed at the rate.
    - `rate` (number): Tax rate in percent.
    - `taxAmount` (number): Tax amount at the rate.
  - `taxTotal` (number): Tax total.
  - `vendor` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text (single invoice only).
- `id` (string (uuid)): Id of the inbound invoice.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): The supplier's invoice number.
- `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
  - `articleAssignment` (object): How the article was resolved.
    - `confidence` (number): Confidence of the article assignment (0–1).
    - `evidence` (string): What the article assignment is based on.
    - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
  - `articleNumber` (string): Internal article number (masterdata).
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `ignored` (boolean): Article on the configured ignore list.
  - `mpn` (string): Manufacturer part number.
  - `netAmount` (number): Net amount of the line.
  - `orderLineRef` (string): Order line the line refers to (BT-132).
  - `orderNumber` (string): Order number the line refers to.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number.
- `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
  - `article` (string): Article of the line.
  - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
  - `description` (string): Human-readable explanation.
  - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
  - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
  - `variance` (number): Variance found (amount or quantity).
- `matchResult` (MatchResult)
  - `evaluatedAt` (string (date-time)): When the match ran.
  - `isBlocked` (boolean): A blocking lock reason was found.
  - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
  - `lockReasons` (array of LockReason): Lock reasons found.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchedLines` (array of object): Result per invoice line.
    - `articleNumber` (string): Article number in masterdata.
    - `availableQty` (number): Received minus already invoiced.
    - `description` (string): Description of the line.
    - `invoicePosition` (integer): Position on the invoice.
    - `invoicedPrice` (number): Unit price invoiced.
    - `invoicedQty` (number): Quantity invoiced.
    - `isMatched` (boolean): The line matches within the tolerances.
    - `poPosition` (integer): Position on the purchase order.
    - `poPrice` (number): Unit price ordered.
    - `poQty` (number): Quantity ordered.
    - `priceVariance` (number): Unit price variance.
    - `qtyVariance` (number): Quantity variance.
    - `receivedQty` (number): Quantity received.
    - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
  - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
  - `totalVariance` (number): Sum of the price variances.
- `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
- `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
- `netTotal` (number): Net total.
- `partnerReference` (string): Our order number as printed on the invoice.
- `paymentTermsText` (string): Payment terms as printed text.
- `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
  - `startedAt` (string (date-time)): When the current processing started.
  - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
- `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
- `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
  - `code` (string): Code of the lock reason.
  - `comment` (string): Why it was accepted.
  - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
  - `resolvedAt` (string (date-time)): When it was accepted.
  - `resolvedBy` (string): Who accepted it.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `skontoTerms` (any): Cash discount terms.
- `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
- `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Gross total of the invoice.
- `totalAmountEur` (number): Gross total in EUR (ECB rate).
- `transactionNumber` (string): Internal number.
- `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
- `updatedAt` (string (date-time)): When the inbound invoice was last changed.
- `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
- `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
- `vendorName` (string): Name of the supplier as stated on the invoice.
- `vendorVatId` (string): Manual correction of the supplier's VAT ID.

Example 200 answer:

```json
{
  "createdAt": "2026-11-19T08:02:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "duplicateOf": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a01",
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a05",
  "invoiceDate": "2026-10-02",
  "invoiceNumber": "RE-482117",
  "lockReasons": [
    {
      "code": "DUPLIKAT",
      "description": "Die Rechnung RE-482117 des Lieferanten liegt bereits als ER-2026-00031 vor.",
      "isBlocking": true,
      "position": 0
    }
  ],
  "netTotal": 5808,
  "sourceKind": "XRECHNUNG_CII",
  "status": "REJECTED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "taxTotal": 1103.52,
  "tenantName": "DEMO",
  "totalAmount": 6911.52,
  "transactionNumber": "ER-2026-00045",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-11-19T08:30:00Z",
  "vendorName": "Nordlicht IT-Distribution GmbH"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/reject' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"comment":"Preisabweichung mit Lieferant geklärt.","override":true}'
```

## Run the pipeline again (tenant:trade:inbound:write)

`POST /api/trade/v1/inbound-invoices/{id}/reprocess`

Module: Trade · operationId: `reprocessInboundInvoice` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

For invoices in `RECEIVED`, `OCR_DONE` or `FAILED` that are not being processed; reads the DMS document
again. The run is recorded in the protocol (action `REPROCESSED`, with the person and the previous
error) and continues in the background: the answer carries `processing`. A DMS failure marks the
invoice `FAILED` and answers it. No request body.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The invoice with the started run (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** The current state does not allow the action (`code` `invalid_state` or `blocked`). (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
  - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
  - `extracted` (object): The supplier as read from the document.
  - `supplier` (object): The assigned master data supplier.
  - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
    - `cached` (boolean): The result came from the 24-hour cache of master data.
    - `checkedAt` (string (date-time)): When the VAT id was checked.
    - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
    - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
    - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
    - `statusDisplay` (string): The status as German text.
    - `statusMessage` (string): Message of the checking service, if any.
    - `vatId` (string): VAT id checked.
- `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
  - `eligible` (boolean): Every condition holds.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `reasons` (array of string): Each failed condition (German text).
  - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
  - `rule` (string): The rule that applied, also the protocol note of the release.
  - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
- `createdAt` (string (date-time)): When the inbound invoice was created.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string): Customer number of the tenant.
- `deliveryDate` (string (date)): Delivery date.
- `dmsDocumentId` (string (uuid)): DMS document of the invoice.
- `dueDate` (string (date)): Due date.
- `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
- `error` (string): Why processing failed (status `FAILED`).
- `exchangeRate` (number): Exchange rate to EUR.
- `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
  - `confidence` (object): Per field (AI extraction only).
  - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
  - `currency` (string): Currency (ISO 4217).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
  - `discountTerms` (array of object): Cash discount terms.
    - `days` (integer): Days within which the discount applies.
    - `percent` (number): Discount in percent.
  - `discountText` (string): Cash discount terms as printed.
  - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
  - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
  - `dueDate` (string): Due date (YYYY-MM-DD).
  - `grossTotal` (number): Gross total.
  - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
  - `invoiceNumber` (string): Invoice number.
  - `isReverseCharge` (boolean): The invoice is reverse charge.
  - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number): Net total.
  - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
  - `orderNumber` (string): Order number stated on the invoice.
  - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
  - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
  - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
  - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
  - `recipient` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
  - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
  - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
  - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `taxExemptionReason` (string): Stated reason for a tax exemption.
  - `taxRates` (array of object): Tax breakdown per rate.
    - `netAmount` (number): Net amount taxed at the rate.
    - `rate` (number): Tax rate in percent.
    - `taxAmount` (number): Tax amount at the rate.
  - `taxTotal` (number): Tax total.
  - `vendor` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text (single invoice only).
- `id` (string (uuid)): Id of the inbound invoice.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): The supplier's invoice number.
- `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
  - `articleAssignment` (object): How the article was resolved.
    - `confidence` (number): Confidence of the article assignment (0–1).
    - `evidence` (string): What the article assignment is based on.
    - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
  - `articleNumber` (string): Internal article number (masterdata).
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `ignored` (boolean): Article on the configured ignore list.
  - `mpn` (string): Manufacturer part number.
  - `netAmount` (number): Net amount of the line.
  - `orderLineRef` (string): Order line the line refers to (BT-132).
  - `orderNumber` (string): Order number the line refers to.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number.
- `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
  - `article` (string): Article of the line.
  - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
  - `description` (string): Human-readable explanation.
  - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
  - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
  - `variance` (number): Variance found (amount or quantity).
- `matchResult` (MatchResult)
  - `evaluatedAt` (string (date-time)): When the match ran.
  - `isBlocked` (boolean): A blocking lock reason was found.
  - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
  - `lockReasons` (array of LockReason): Lock reasons found.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchedLines` (array of object): Result per invoice line.
    - `articleNumber` (string): Article number in masterdata.
    - `availableQty` (number): Received minus already invoiced.
    - `description` (string): Description of the line.
    - `invoicePosition` (integer): Position on the invoice.
    - `invoicedPrice` (number): Unit price invoiced.
    - `invoicedQty` (number): Quantity invoiced.
    - `isMatched` (boolean): The line matches within the tolerances.
    - `poPosition` (integer): Position on the purchase order.
    - `poPrice` (number): Unit price ordered.
    - `poQty` (number): Quantity ordered.
    - `priceVariance` (number): Unit price variance.
    - `qtyVariance` (number): Quantity variance.
    - `receivedQty` (number): Quantity received.
    - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
  - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
  - `totalVariance` (number): Sum of the price variances.
- `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
- `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
- `netTotal` (number): Net total.
- `partnerReference` (string): Our order number as printed on the invoice.
- `paymentTermsText` (string): Payment terms as printed text.
- `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
  - `startedAt` (string (date-time)): When the current processing started.
  - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
- `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
- `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
  - `code` (string): Code of the lock reason.
  - `comment` (string): Why it was accepted.
  - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
  - `resolvedAt` (string (date-time)): When it was accepted.
  - `resolvedBy` (string): Who accepted it.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `skontoTerms` (any): Cash discount terms.
- `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
- `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Gross total of the invoice.
- `totalAmountEur` (number): Gross total in EUR (ECB rate).
- `transactionNumber` (string): Internal number.
- `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
- `updatedAt` (string (date-time)): When the inbound invoice was last changed.
- `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
- `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
- `vendorName` (string): Name of the supplier as stated on the invoice.
- `vendorVatId` (string): Manual correction of the supplier's VAT ID.

Example 200 answer:

```json
{
  "addressSnapshot": {
    "assignment": {
      "confidence": 1,
      "evidence": "USt-IdNr. DE701000001",
      "method": "exact_vat"
    },
    "extracted": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    },
    "supplier": {
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "name": "Nordlicht IT-Distribution GmbH",
      "supplierNumber": "70001"
    },
    "vatCheck": {
      "cached": false,
      "checkedAt": "2026-10-05T08:41:10Z",
      "method": "VIES",
      "serviceUnavailable": false,
      "status": "OFFICIALLY_CONFIRMED",
      "statusDisplay": "Gültig",
      "vatId": "DE701000001"
    }
  },
  "autoRelease": {
    "eligible": false,
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "mode": "dryRun",
    "reasons": [
      "Bruttobetrag 6.911,52 € liegt über der Grenze von 2.500,00 €."
    ],
    "released": false,
    "suppressed": false
  },
  "createdAt": "2026-10-05T08:40:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-10-01",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b01",
  "dueDate": "2026-11-01",
  "exchangeRate": 1,
  "extraction": {
    "currency": "EUR",
    "customerNumber": "K-99871",
    "deliveryDate": "2026-10-01",
    "documentType": "380",
    "documentTypeCode": "380",
    "dueDate": "2026-11-01",
    "grossTotal": 6911.52,
    "invoiceDate": "2026-10-02",
    "invoiceNumber": "RE-482117",
    "isReverseCharge": false,
    "lines": [
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1001",
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "ean": "4061234500014",
        "ignored": false,
        "netAmount": 4974,
        "orderNumber": "BE-2026-00058",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 829,
        "vendorArticleNo": "NL-PB14G10-16"
      },
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-DOCKC100",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1004",
        "description": "USB-C Dockingstation 100 W",
        "ean": "4061234500045",
        "ignored": false,
        "netAmount": 834,
        "orderNumber": "BE-2026-00058",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 139,
        "vendorArticleNo": "NL-DOCKC100"
      }
    ],
    "netDays": 30,
    "netTotal": 5808,
    "orderNumber": "BE-2026-00058",
    "paymentMeansCode": "58",
    "paymentMeansText": "SEPA-Überweisung",
    "paymentText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
    "recipient": {
      "city": "Regensburg",
      "country": "DE",
      "name": "Muster IT-Systemhaus GmbH",
      "street": "Industriestraße 12",
      "vatId": "DE999000111",
      "zip": "93055"
    },
    "sourceKind": "XRECHNUNG_CII",
    "taxRates": [
      {
        "netAmount": 5808,
        "rate": 19,
        "taxAmount": 1103.52
      }
    ],
    "taxTotal": 1103.52,
    "vendor": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    }
  },
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a01",
  "invoiceDate": "2026-10-02",
  "invoiceNumber": "RE-482117",
  "lineItems": [
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1001",
      "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
      "ean": "4061234500014",
      "ignored": false,
      "netAmount": 4974,
      "orderNumber": "BE-2026-00058",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 829,
      "vendorArticleNo": "NL-PB14G10-16"
    },
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-DOCKC100",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1004",
      "description": "USB-C Dockingstation 100 W",
      "ean": "4061234500045",
      "ignored": false,
      "netAmount": 834,
      "orderNumber": "BE-2026-00058",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 139,
      "vendorArticleNo": "NL-DOCKC100"
    }
  ],
  "lockReasons": [],
  "matchResult": {
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "isBlocked": false,
    "isMatched": true,
    "lockReasons": [],
    "matchedLines": [
      {
        "articleNumber": "HW-1001",
        "availableQty": 6,
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "invoicePosition": 1,
        "invoicedPrice": 829,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 1,
        "poPrice": 829,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      },
      {
        "articleNumber": "HW-1004",
        "availableQty": 6,
        "description": "USB-C Dockingstation 100 W",
        "invoicePosition": 2,
        "invoicedPrice": 139,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 2,
        "poPrice": 139,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      }
    ],
    "status": "matched",
    "totalVariance": 0
  },
  "matchingStatus": "matched",
  "netDays": 30,
  "netTotal": 5808,
  "partnerReference": "BE-2026-00058",
  "paymentTermsText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d58",
  "sourceKind": "XRECHNUNG_CII",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "taxTotal": 1103.52,
  "tenantName": "DEMO",
  "totalAmount": 6911.52,
  "totalAmountEur": 6911.52,
  "transactionNumber": "ER-2026-00031",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-10-05T08:41:12Z",
  "validationReport": {
    "findings": [],
    "scenario": "EN16931 XRechnung (CII)",
    "syntax": "CII",
    "valid": true
  },
  "validationStatus": "valid",
  "vendorName": "Nordlicht IT-Distribution GmbH"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/reprocess' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Reopen an automatically released inbound invoice (tenant:trade:inbound:approve)

`POST /api/trade/v1/inbound-invoices/{id}/reopen`

Module: Trade · operationId: `reopenInboundInvoice` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

`RELEASED` → `MATCHED` for an invoice the system released automatically (`autoRelease.released`); publishes
`trade.inboundinvoice.reopened` with the `comment`. The normal workflow takes the invoice from there, and
`autoRelease.suppressed` is set so no later re-check releases it automatically again. An invoice released by a
person, or already reopened, answers `409 invalid_state`; a missing or empty `comment` (max. 1000 characters) `400 invalid`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `comment` (string, required): Why the release is undone. (max length 1000)

Example:

```json
{
  "comment": "Preis stimmt nicht mit der Rahmenvereinbarung überein."
}
```

### Responses

- **200** Reopened invoice (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** The current state does not allow the action (`code` `invalid_state` or `blocked`). (`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 200 answer:

- `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
  - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
  - `extracted` (object): The supplier as read from the document.
  - `supplier` (object): The assigned master data supplier.
  - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
    - `cached` (boolean): The result came from the 24-hour cache of master data.
    - `checkedAt` (string (date-time)): When the VAT id was checked.
    - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
    - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
    - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
    - `statusDisplay` (string): The status as German text.
    - `statusMessage` (string): Message of the checking service, if any.
    - `vatId` (string): VAT id checked.
- `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
  - `eligible` (boolean): Every condition holds.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `reasons` (array of string): Each failed condition (German text).
  - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
  - `rule` (string): The rule that applied, also the protocol note of the release.
  - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
- `createdAt` (string (date-time)): When the inbound invoice was created.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string): Customer number of the tenant.
- `deliveryDate` (string (date)): Delivery date.
- `dmsDocumentId` (string (uuid)): DMS document of the invoice.
- `dueDate` (string (date)): Due date.
- `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
- `error` (string): Why processing failed (status `FAILED`).
- `exchangeRate` (number): Exchange rate to EUR.
- `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
  - `confidence` (object): Per field (AI extraction only).
  - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
  - `currency` (string): Currency (ISO 4217).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
  - `discountTerms` (array of object): Cash discount terms.
    - `days` (integer): Days within which the discount applies.
    - `percent` (number): Discount in percent.
  - `discountText` (string): Cash discount terms as printed.
  - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
  - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
  - `dueDate` (string): Due date (YYYY-MM-DD).
  - `grossTotal` (number): Gross total.
  - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
  - `invoiceNumber` (string): Invoice number.
  - `isReverseCharge` (boolean): The invoice is reverse charge.
  - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number): Net total.
  - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
  - `orderNumber` (string): Order number stated on the invoice.
  - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
  - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
  - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
  - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
  - `recipient` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
  - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
  - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
  - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `taxExemptionReason` (string): Stated reason for a tax exemption.
  - `taxRates` (array of object): Tax breakdown per rate.
    - `netAmount` (number): Net amount taxed at the rate.
    - `rate` (number): Tax rate in percent.
    - `taxAmount` (number): Tax amount at the rate.
  - `taxTotal` (number): Tax total.
  - `vendor` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text (single invoice only).
- `id` (string (uuid)): Id of the inbound invoice.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): The supplier's invoice number.
- `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
  - `articleAssignment` (object): How the article was resolved.
    - `confidence` (number): Confidence of the article assignment (0–1).
    - `evidence` (string): What the article assignment is based on.
    - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
  - `articleNumber` (string): Internal article number (masterdata).
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `ignored` (boolean): Article on the configured ignore list.
  - `mpn` (string): Manufacturer part number.
  - `netAmount` (number): Net amount of the line.
  - `orderLineRef` (string): Order line the line refers to (BT-132).
  - `orderNumber` (string): Order number the line refers to.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number.
- `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
  - `article` (string): Article of the line.
  - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
  - `description` (string): Human-readable explanation.
  - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
  - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
  - `variance` (number): Variance found (amount or quantity).
- `matchResult` (MatchResult)
  - `evaluatedAt` (string (date-time)): When the match ran.
  - `isBlocked` (boolean): A blocking lock reason was found.
  - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
  - `lockReasons` (array of LockReason): Lock reasons found.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchedLines` (array of object): Result per invoice line.
    - `articleNumber` (string): Article number in masterdata.
    - `availableQty` (number): Received minus already invoiced.
    - `description` (string): Description of the line.
    - `invoicePosition` (integer): Position on the invoice.
    - `invoicedPrice` (number): Unit price invoiced.
    - `invoicedQty` (number): Quantity invoiced.
    - `isMatched` (boolean): The line matches within the tolerances.
    - `poPosition` (integer): Position on the purchase order.
    - `poPrice` (number): Unit price ordered.
    - `poQty` (number): Quantity ordered.
    - `priceVariance` (number): Unit price variance.
    - `qtyVariance` (number): Quantity variance.
    - `receivedQty` (number): Quantity received.
    - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
  - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
  - `totalVariance` (number): Sum of the price variances.
- `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
- `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
- `netTotal` (number): Net total.
- `partnerReference` (string): Our order number as printed on the invoice.
- `paymentTermsText` (string): Payment terms as printed text.
- `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
  - `startedAt` (string (date-time)): When the current processing started.
  - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
- `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
- `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
  - `code` (string): Code of the lock reason.
  - `comment` (string): Why it was accepted.
  - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
  - `resolvedAt` (string (date-time)): When it was accepted.
  - `resolvedBy` (string): Who accepted it.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `skontoTerms` (any): Cash discount terms.
- `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
- `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Gross total of the invoice.
- `totalAmountEur` (number): Gross total in EUR (ECB rate).
- `transactionNumber` (string): Internal number.
- `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
- `updatedAt` (string (date-time)): When the inbound invoice was last changed.
- `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
- `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
- `vendorName` (string): Name of the supplier as stated on the invoice.
- `vendorVatId` (string): Manual correction of the supplier's VAT ID.

Example 200 answer:

```json
{
  "addressSnapshot": {
    "assignment": {
      "confidence": 1,
      "evidence": "USt-IdNr. DE701000001",
      "method": "exact_vat"
    },
    "extracted": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    },
    "supplier": {
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "name": "Nordlicht IT-Distribution GmbH",
      "supplierNumber": "70001"
    },
    "vatCheck": {
      "cached": false,
      "checkedAt": "2026-10-05T08:41:10Z",
      "method": "VIES",
      "serviceUnavailable": false,
      "status": "OFFICIALLY_CONFIRMED",
      "statusDisplay": "Gültig",
      "vatId": "DE701000001"
    }
  },
  "autoRelease": {
    "eligible": false,
    "evaluatedAt": "2026-10-07T11:00:00Z",
    "mode": "on",
    "reasons": [
      "Freigabe wurde zurückgenommen."
    ],
    "released": false,
    "rule": "Lieferant vertraut, Betrag unter 7.500,00 €",
    "suppressed": true
  },
  "createdAt": "2026-10-05T08:40:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-10-01",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b01",
  "dueDate": "2026-11-01",
  "exchangeRate": 1,
  "extraction": {
    "currency": "EUR",
    "customerNumber": "K-99871",
    "deliveryDate": "2026-10-01",
    "documentType": "380",
    "documentTypeCode": "380",
    "dueDate": "2026-11-01",
    "grossTotal": 6911.52,
    "invoiceDate": "2026-10-02",
    "invoiceNumber": "RE-482117",
    "isReverseCharge": false,
    "lines": [
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1001",
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "ean": "4061234500014",
        "ignored": false,
        "netAmount": 4974,
        "orderNumber": "BE-2026-00058",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 829,
        "vendorArticleNo": "NL-PB14G10-16"
      },
      {
        "articleAssignment": {
          "confidence": 1,
          "evidence": "Lieferantenartikelnummer NL-DOCKC100",
          "method": "supplier_number"
        },
        "articleNumber": "HW-1004",
        "description": "USB-C Dockingstation 100 W",
        "ean": "4061234500045",
        "ignored": false,
        "netAmount": 834,
        "orderNumber": "BE-2026-00058",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
        "quantity": 6,
        "taxRate": 19,
        "unit": "STK",
        "unitPrice": 139,
        "vendorArticleNo": "NL-DOCKC100"
      }
    ],
    "netDays": 30,
    "netTotal": 5808,
    "orderNumber": "BE-2026-00058",
    "paymentMeansCode": "58",
    "paymentMeansText": "SEPA-Überweisung",
    "paymentText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
    "recipient": {
      "city": "Regensburg",
      "country": "DE",
      "name": "Muster IT-Systemhaus GmbH",
      "street": "Industriestraße 12",
      "vatId": "DE999000111",
      "zip": "93055"
    },
    "sourceKind": "XRECHNUNG_CII",
    "taxRates": [
      {
        "netAmount": 5808,
        "rate": 19,
        "taxAmount": 1103.52
      }
    ],
    "taxTotal": 1103.52,
    "vendor": {
      "city": "Hamburg",
      "country": "DE",
      "iban": "DE02100100100006820101",
      "name": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zip": "20457"
    }
  },
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a01",
  "invoiceDate": "2026-10-02",
  "invoiceNumber": "RE-482117",
  "lineItems": [
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-PB14G10-16",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1001",
      "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
      "ean": "4061234500014",
      "ignored": false,
      "netAmount": 4974,
      "orderNumber": "BE-2026-00058",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d01",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 829,
      "vendorArticleNo": "NL-PB14G10-16"
    },
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-DOCKC100",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1004",
      "description": "USB-C Dockingstation 100 W",
      "ean": "4061234500045",
      "ignored": false,
      "netAmount": 834,
      "orderNumber": "BE-2026-00058",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
      "quantity": 6,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 139,
      "vendorArticleNo": "NL-DOCKC100"
    }
  ],
  "lockReasons": [],
  "matchResult": {
    "evaluatedAt": "2026-10-05T08:41:12Z",
    "isBlocked": false,
    "isMatched": true,
    "lockReasons": [],
    "matchedLines": [
      {
        "articleNumber": "HW-1001",
        "availableQty": 6,
        "description": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "invoicePosition": 1,
        "invoicedPrice": 829,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 1,
        "poPrice": 829,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      },
      {
        "articleNumber": "HW-1004",
        "availableQty": 6,
        "description": "USB-C Dockingstation 100 W",
        "invoicePosition": 2,
        "invoicedPrice": 139,
        "invoicedQty": 6,
        "isMatched": true,
        "poPosition": 2,
        "poPrice": 139,
        "poQty": 6,
        "priceVariance": 0,
        "qtyVariance": 0,
        "receivedQty": 6,
        "varianceType": "NONE"
      }
    ],
    "status": "matched",
    "totalVariance": 0
  },
  "matchingStatus": "matched",
  "netDays": 30,
  "netTotal": 5808,
  "partnerReference": "BE-2026-00058",
  "paymentTermsText": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d58",
  "sourceKind": "XRECHNUNG_CII",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "taxTotal": 1103.52,
  "tenantName": "DEMO",
  "totalAmount": 6911.52,
  "totalAmountEur": 6911.52,
  "transactionNumber": "ER-2026-00031",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-10-07T11:00:00Z",
  "validationReport": {
    "findings": [],
    "scenario": "EN16931 XRechnung (CII)",
    "syntax": "CII",
    "valid": true
  },
  "validationStatus": "valid",
  "vendorName": "Nordlicht IT-Distribution GmbH"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/reopen' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"comment":"Preis stimmt nicht mit der Rahmenvereinbarung überein."}'
```

## List the purchase orders and goods receipts of an inbound invoice (tenant:trade:inbound:read)

`GET /api/trade/v1/inbound-invoices/{id}/related`

Module: Trade · operationId: `listInboundInvoiceRelatedDocuments` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

The matched purchase order and those the order numbers of the invoice (header and lines) name, each with its goods receipts.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Related documents (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `goodsReceipts` (array of object): Goods receipts of those purchase orders.
  - `grNumber` (string): Number of the goods receipt.
  - `id` (string (uuid)): Id of the goods receipt.
  - `poId` (string (uuid)): Id of the purchase order.
  - `poNumber` (string): Number of the purchase order.
  - `receivedAt` (string (date-time)): When the goods were received.
  - `status` (string): Status of the goods receipt.
- `purchaseOrders` (array of object): Purchase orders of the invoice.
  - `id` (string (uuid)): Id of the purchase order.
  - `matched` (boolean): The purchase order the invoice was matched against.
  - `orderDate` (string (date)): Order date.
  - `poNumber` (string): Number of the purchase order.
  - `status` (string): Status of the purchase order.

Example 200 answer:

```json
{
  "goodsReceipts": [
    {
      "grNumber": "WE-2026-00041",
      "id": "3d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f41",
      "poId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d58",
      "poNumber": "BE-2026-00058",
      "receivedAt": "2026-10-01T09:10:00Z",
      "status": "posted"
    }
  ],
  "purchaseOrders": [
    {
      "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d58",
      "matched": true,
      "orderDate": "2026-09-24",
      "poNumber": "BE-2026-00058",
      "status": "received"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/related' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Accept a blocking lock reason (tenant:trade:inbound:write)

`POST /api/trade/v1/inbound-invoices/{id}/lock-reasons/resolve`

Module: Trade · operationId: `resolveInboundInvoiceLockReason` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

Accepts a blocking lock reason (`code` and, for line reasons, `position`) with an optional comment and
checks the invoice again; the reason stays listed with `isBlocking: false` and the acceptance is in
`resolvedLockReasons` until the document is read anew. Accepting `DUPLIKAT` matches the invoice like
any other. `FEHLENDER_LIEFERANT` and `FEHLENDER_ARTIKEL` are fixed by an assignment (`422`). Allowed in
the statuses of corrections; recorded in the protocol.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `code` (string, required): Code of the lock reason (e.g. `PREISABWEICHUNG`). (max length 64)
- `comment` (string): Why it is accepted or withdrawn. (max length 2000)
- `position` (integer): The line of a line reason; 0 or missing for header reasons.

Example:

```json
{
  "code": "PREISABWEICHUNG",
  "comment": "Preiserhöhung des Herstellers zum 01.10.2026, mit Nordlicht abgestimmt.",
  "position": 1
}
```

### Responses

- **200** The invoice checked again (`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 current state does not allow the action (`code` `invalid_state` or `blocked`). (`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 200 answer:

- `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
  - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
  - `extracted` (object): The supplier as read from the document.
  - `supplier` (object): The assigned master data supplier.
  - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
    - `cached` (boolean): The result came from the 24-hour cache of master data.
    - `checkedAt` (string (date-time)): When the VAT id was checked.
    - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
    - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
    - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
    - `statusDisplay` (string): The status as German text.
    - `statusMessage` (string): Message of the checking service, if any.
    - `vatId` (string): VAT id checked.
- `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
  - `eligible` (boolean): Every condition holds.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `reasons` (array of string): Each failed condition (German text).
  - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
  - `rule` (string): The rule that applied, also the protocol note of the release.
  - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
- `createdAt` (string (date-time)): When the inbound invoice was created.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string): Customer number of the tenant.
- `deliveryDate` (string (date)): Delivery date.
- `dmsDocumentId` (string (uuid)): DMS document of the invoice.
- `dueDate` (string (date)): Due date.
- `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
- `error` (string): Why processing failed (status `FAILED`).
- `exchangeRate` (number): Exchange rate to EUR.
- `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
  - `confidence` (object): Per field (AI extraction only).
  - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
  - `currency` (string): Currency (ISO 4217).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
  - `discountTerms` (array of object): Cash discount terms.
    - `days` (integer): Days within which the discount applies.
    - `percent` (number): Discount in percent.
  - `discountText` (string): Cash discount terms as printed.
  - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
  - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
  - `dueDate` (string): Due date (YYYY-MM-DD).
  - `grossTotal` (number): Gross total.
  - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
  - `invoiceNumber` (string): Invoice number.
  - `isReverseCharge` (boolean): The invoice is reverse charge.
  - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number): Net total.
  - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
  - `orderNumber` (string): Order number stated on the invoice.
  - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
  - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
  - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
  - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
  - `recipient` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
  - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
  - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
  - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `taxExemptionReason` (string): Stated reason for a tax exemption.
  - `taxRates` (array of object): Tax breakdown per rate.
    - `netAmount` (number): Net amount taxed at the rate.
    - `rate` (number): Tax rate in percent.
    - `taxAmount` (number): Tax amount at the rate.
  - `taxTotal` (number): Tax total.
  - `vendor` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text (single invoice only).
- `id` (string (uuid)): Id of the inbound invoice.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): The supplier's invoice number.
- `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
  - `articleAssignment` (object): How the article was resolved.
    - `confidence` (number): Confidence of the article assignment (0–1).
    - `evidence` (string): What the article assignment is based on.
    - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
  - `articleNumber` (string): Internal article number (masterdata).
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `ignored` (boolean): Article on the configured ignore list.
  - `mpn` (string): Manufacturer part number.
  - `netAmount` (number): Net amount of the line.
  - `orderLineRef` (string): Order line the line refers to (BT-132).
  - `orderNumber` (string): Order number the line refers to.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number.
- `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
  - `article` (string): Article of the line.
  - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
  - `description` (string): Human-readable explanation.
  - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
  - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
  - `variance` (number): Variance found (amount or quantity).
- `matchResult` (MatchResult)
  - `evaluatedAt` (string (date-time)): When the match ran.
  - `isBlocked` (boolean): A blocking lock reason was found.
  - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
  - `lockReasons` (array of LockReason): Lock reasons found.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchedLines` (array of object): Result per invoice line.
    - `articleNumber` (string): Article number in masterdata.
    - `availableQty` (number): Received minus already invoiced.
    - `description` (string): Description of the line.
    - `invoicePosition` (integer): Position on the invoice.
    - `invoicedPrice` (number): Unit price invoiced.
    - `invoicedQty` (number): Quantity invoiced.
    - `isMatched` (boolean): The line matches within the tolerances.
    - `poPosition` (integer): Position on the purchase order.
    - `poPrice` (number): Unit price ordered.
    - `poQty` (number): Quantity ordered.
    - `priceVariance` (number): Unit price variance.
    - `qtyVariance` (number): Quantity variance.
    - `receivedQty` (number): Quantity received.
    - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
  - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
  - `totalVariance` (number): Sum of the price variances.
- `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
- `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
- `netTotal` (number): Net total.
- `partnerReference` (string): Our order number as printed on the invoice.
- `paymentTermsText` (string): Payment terms as printed text.
- `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
  - `startedAt` (string (date-time)): When the current processing started.
  - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
- `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
- `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
  - `code` (string): Code of the lock reason.
  - `comment` (string): Why it was accepted.
  - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
  - `resolvedAt` (string (date-time)): When it was accepted.
  - `resolvedBy` (string): Who accepted it.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `skontoTerms` (any): Cash discount terms.
- `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
- `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Gross total of the invoice.
- `totalAmountEur` (number): Gross total in EUR (ECB rate).
- `transactionNumber` (string): Internal number.
- `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
- `updatedAt` (string (date-time)): When the inbound invoice was last changed.
- `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
- `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
- `vendorName` (string): Name of the supplier as stated on the invoice.
- `vendorVatId` (string): Manual correction of the supplier's VAT ID.

Example 200 answer:

```json
{
  "createdAt": "2026-10-26T08:35:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-10-22",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b02",
  "dueDate": "2026-11-22",
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a02",
  "invoiceDate": "2026-10-23",
  "invoiceNumber": "RE-483350",
  "lineItems": [
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-EB860G11-32",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1002",
      "description": "Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD",
      "ean": "4061234500021",
      "ignored": false,
      "netAmount": 4347,
      "orderNumber": "BE-2026-00062",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d02",
      "quantity": 3,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 1449,
      "vendorArticleNo": "NL-EB860G11-32"
    }
  ],
  "lockReasons": [
    {
      "article": "HW-1002",
      "code": "PREISABWEICHUNG",
      "description": "Pos. 1: berechnet 1.449,00 €, bestellt zu 1.389,00 € (+60,00 € je Stück).",
      "isBlocking": true,
      "position": 1,
      "variance": 60
    }
  ],
  "matchResult": {
    "evaluatedAt": "2026-10-26T08:36:02Z",
    "isBlocked": true,
    "isMatched": false,
    "lockReasons": [
      {
        "article": "HW-1002",
        "code": "PREISABWEICHUNG",
        "description": "Pos. 1: berechnet 1.449,00 €, bestellt zu 1.389,00 € (+60,00 € je Stück).",
        "isBlocking": true,
        "position": 1,
        "variance": 60
      }
    ],
    "matchedLines": [
      {
        "articleNumber": "HW-1002",
        "availableQty": 3,
        "description": "Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD",
        "invoicePosition": 1,
        "invoicedPrice": 1449,
        "invoicedQty": 3,
        "isMatched": false,
        "poPosition": 1,
        "poPrice": 1389,
        "poQty": 3,
        "priceVariance": 60,
        "qtyVariance": 0,
        "receivedQty": 3,
        "varianceType": "PRICE"
      }
    ],
    "status": "blocked",
    "totalVariance": 180
  },
  "matchingStatus": "matched",
  "netDays": 30,
  "netTotal": 4347,
  "partnerReference": "BE-2026-00062",
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d62",
  "resolvedLockReasons": [
    {
      "code": "PREISABWEICHUNG",
      "comment": "Preiserhöhung des Herstellers zum 01.10.2026, mit Nordlicht abgestimmt.",
      "position": 1,
      "resolvedAt": "2026-10-27T10:15:00Z",
      "resolvedBy": "anna.weber@muster-it.example"
    }
  ],
  "sourceKind": "XRECHNUNG_CII",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "taxTotal": 825.93,
  "tenantName": "DEMO",
  "totalAmount": 5172.93,
  "totalAmountEur": 5172.93,
  "transactionNumber": "ER-2026-00036",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-10-27T10:15:00Z",
  "validationStatus": "valid",
  "vendorName": "Nordlicht IT-Distribution GmbH"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/lock-reasons/resolve' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"code":"PREISABWEICHUNG","comment":"Preiserhöhung des Herstellers zum 01.10.2026, mit Nordlicht abgestimmt.","position":1}'
```

## Withdraw the acceptance of a lock reason (tenant:trade:inbound:write)

`POST /api/trade/v1/inbound-invoices/{id}/lock-reasons/reopen`

Module: Trade · operationId: `reopenInboundInvoiceLockReason` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

Removes the acceptance of the lock reason and checks the invoice again; without an acceptance the invoice is answered unchanged.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `code` (string, required): Code of the lock reason (e.g. `PREISABWEICHUNG`). (max length 64)
- `comment` (string): Why it is accepted or withdrawn. (max length 2000)
- `position` (integer): The line of a line reason; 0 or missing for header reasons.

Example:

```json
{
  "code": "PREISABWEICHUNG",
  "comment": "Nordlicht hat die Preiserhöhung doch nicht bestätigt – Gutschrift anfordern.",
  "position": 1
}
```

### Responses

- **200** The invoice checked again (`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 current state does not allow the action (`code` `invalid_state` or `blocked`). (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
  - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
  - `extracted` (object): The supplier as read from the document.
  - `supplier` (object): The assigned master data supplier.
  - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
    - `cached` (boolean): The result came from the 24-hour cache of master data.
    - `checkedAt` (string (date-time)): When the VAT id was checked.
    - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
    - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
    - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
    - `statusDisplay` (string): The status as German text.
    - `statusMessage` (string): Message of the checking service, if any.
    - `vatId` (string): VAT id checked.
- `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
  - `eligible` (boolean): Every condition holds.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `reasons` (array of string): Each failed condition (German text).
  - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
  - `rule` (string): The rule that applied, also the protocol note of the release.
  - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
- `createdAt` (string (date-time)): When the inbound invoice was created.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string): Customer number of the tenant.
- `deliveryDate` (string (date)): Delivery date.
- `dmsDocumentId` (string (uuid)): DMS document of the invoice.
- `dueDate` (string (date)): Due date.
- `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
- `error` (string): Why processing failed (status `FAILED`).
- `exchangeRate` (number): Exchange rate to EUR.
- `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
  - `confidence` (object): Per field (AI extraction only).
  - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
  - `currency` (string): Currency (ISO 4217).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
  - `discountTerms` (array of object): Cash discount terms.
    - `days` (integer): Days within which the discount applies.
    - `percent` (number): Discount in percent.
  - `discountText` (string): Cash discount terms as printed.
  - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
  - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
  - `dueDate` (string): Due date (YYYY-MM-DD).
  - `grossTotal` (number): Gross total.
  - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
  - `invoiceNumber` (string): Invoice number.
  - `isReverseCharge` (boolean): The invoice is reverse charge.
  - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number): Net total.
  - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
  - `orderNumber` (string): Order number stated on the invoice.
  - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
  - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
  - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
  - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
  - `recipient` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
  - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
  - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
  - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `taxExemptionReason` (string): Stated reason for a tax exemption.
  - `taxRates` (array of object): Tax breakdown per rate.
    - `netAmount` (number): Net amount taxed at the rate.
    - `rate` (number): Tax rate in percent.
    - `taxAmount` (number): Tax amount at the rate.
  - `taxTotal` (number): Tax total.
  - `vendor` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text (single invoice only).
- `id` (string (uuid)): Id of the inbound invoice.
- `invoiceDate` (string (date)): Invoice date.
- `invoiceNumber` (string): The supplier's invoice number.
- `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
  - `articleAssignment` (object): How the article was resolved.
    - `confidence` (number): Confidence of the article assignment (0–1).
    - `evidence` (string): What the article assignment is based on.
    - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
  - `articleNumber` (string): Internal article number (masterdata).
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `ignored` (boolean): Article on the configured ignore list.
  - `mpn` (string): Manufacturer part number.
  - `netAmount` (number): Net amount of the line.
  - `orderLineRef` (string): Order line the line refers to (BT-132).
  - `orderNumber` (string): Order number the line refers to.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
  - `vendorArticleNo` (string): The supplier's article number.
- `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
  - `article` (string): Article of the line.
  - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
  - `description` (string): Human-readable explanation.
  - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
  - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
  - `variance` (number): Variance found (amount or quantity).
- `matchResult` (MatchResult)
  - `evaluatedAt` (string (date-time)): When the match ran.
  - `isBlocked` (boolean): A blocking lock reason was found.
  - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
  - `lockReasons` (array of LockReason): Lock reasons found.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchedLines` (array of object): Result per invoice line.
    - `articleNumber` (string): Article number in masterdata.
    - `availableQty` (number): Received minus already invoiced.
    - `description` (string): Description of the line.
    - `invoicePosition` (integer): Position on the invoice.
    - `invoicedPrice` (number): Unit price invoiced.
    - `invoicedQty` (number): Quantity invoiced.
    - `isMatched` (boolean): The line matches within the tolerances.
    - `poPosition` (integer): Position on the purchase order.
    - `poPrice` (number): Unit price ordered.
    - `poQty` (number): Quantity ordered.
    - `priceVariance` (number): Unit price variance.
    - `qtyVariance` (number): Quantity variance.
    - `receivedQty` (number): Quantity received.
    - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
  - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
  - `totalVariance` (number): Sum of the price variances.
- `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
- `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
- `netTotal` (number): Net total.
- `partnerReference` (string): Our order number as printed on the invoice.
- `paymentTermsText` (string): Payment terms as printed text.
- `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
  - `startedAt` (string (date-time)): When the current processing started.
  - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
- `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
- `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
  - `code` (string): Code of the lock reason.
  - `comment` (string): Why it was accepted.
  - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
  - `resolvedAt` (string (date-time)): When it was accepted.
  - `resolvedBy` (string): Who accepted it.
- `skontoDays1` (integer): Days of the first cash discount.
- `skontoDays2` (integer): Days of the second cash discount.
- `skontoRate1` (number): Rate in percent of the first cash discount.
- `skontoRate2` (number): Rate in percent of the second cash discount.
- `skontoTerms` (any): Cash discount terms.
- `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
- `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `taxTotal` (number): Tax total.
- `tenantName` (string): Name of the tenant.
- `totalAmount` (number): Gross total of the invoice.
- `totalAmountEur` (number): Gross total in EUR (ECB rate).
- `transactionNumber` (string): Internal number.
- `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
- `updatedAt` (string (date-time)): When the inbound invoice was last changed.
- `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
- `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
- `vendorName` (string): Name of the supplier as stated on the invoice.
- `vendorVatId` (string): Manual correction of the supplier's VAT ID.

Example 200 answer:

```json
{
  "createdAt": "2026-10-26T08:35:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-10-22",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b02",
  "dueDate": "2026-11-22",
  "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a02",
  "invoiceDate": "2026-10-23",
  "invoiceNumber": "RE-483350",
  "lineItems": [
    {
      "articleAssignment": {
        "confidence": 1,
        "evidence": "Lieferantenartikelnummer NL-EB860G11-32",
        "method": "supplier_number"
      },
      "articleNumber": "HW-1002",
      "description": "Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD",
      "ean": "4061234500021",
      "ignored": false,
      "netAmount": 4347,
      "orderNumber": "BE-2026-00062",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d02",
      "quantity": 3,
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 1449,
      "vendorArticleNo": "NL-EB860G11-32"
    }
  ],
  "lockReasons": [
    {
      "article": "HW-1002",
      "code": "PREISABWEICHUNG",
      "description": "Pos. 1: berechnet 1.449,00 €, bestellt zu 1.389,00 € (+60,00 € je Stück).",
      "isBlocking": true,
      "position": 1,
      "variance": 60
    }
  ],
  "matchResult": {
    "evaluatedAt": "2026-10-26T08:36:02Z",
    "isBlocked": true,
    "isMatched": false,
    "lockReasons": [
      {
        "article": "HW-1002",
        "code": "PREISABWEICHUNG",
        "description": "Pos. 1: berechnet 1.449,00 €, bestellt zu 1.389,00 € (+60,00 € je Stück).",
        "isBlocking": true,
        "position": 1,
        "variance": 60
      }
    ],
    "matchedLines": [
      {
        "articleNumber": "HW-1002",
        "availableQty": 3,
        "description": "Notebook EliteBook 860 G11, i7, 32 GB, 1 TB SSD",
        "invoicePosition": 1,
        "invoicedPrice": 1449,
        "invoicedQty": 3,
        "isMatched": false,
        "poPosition": 1,
        "poPrice": 1389,
        "poQty": 3,
        "priceVariance": 60,
        "qtyVariance": 0,
        "receivedQty": 3,
        "varianceType": "PRICE"
      }
    ],
    "status": "blocked",
    "totalVariance": 180
  },
  "matchingStatus": "blocked",
  "netDays": 30,
  "netTotal": 4347,
  "partnerReference": "BE-2026-00062",
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d62",
  "sourceKind": "XRECHNUNG_CII",
  "status": "DISCREPANCY",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "taxTotal": 825.93,
  "tenantName": "DEMO",
  "totalAmount": 5172.93,
  "totalAmountEur": 5172.93,
  "transactionNumber": "ER-2026-00036",
  "transactionType": "INBOUND_INVOICE",
  "updatedAt": "2026-10-26T08:36:02Z",
  "validationStatus": "valid",
  "vendorName": "Nordlicht IT-Distribution GmbH"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/lock-reasons/reopen' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"code":"PREISABWEICHUNG","comment":"Nordlicht hat die Preiserhöhung doch nicht bestätigt – Gutschrift anfordern.","position":1}'
```

# Procurement

## List purchase orders (tenant:trade:purchasing:read)

`GET /api/trade/v1/purchase-orders`

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

Newest first (creation time, then id), without lines; pages by keyset (`nextCursor`), `total` counts all matches.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | PurchaseOrderStatus |  | (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`) |
| `supplierAddressId` | query | string (uuid) |  |  |
| `q` | query | string |  | Substring of the order number, the supplier's confirmation number or the supplier name. |
| `limit` | query | integer |  | Page size; at most 500. (default `50`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** Purchase orders (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of PurchaseOrder, required): The purchase orders of the page.
  - `createdAt` (string (date-time)): When the purchase order was created.
  - `currency` (string): Currency (ISO 4217).
  - `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
  - `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
    - `cargoInsurance` (number): Cargo insurance charged.
    - `confirmations` (array of object): Order confirmations of the distributor.
      - `date` (string (date)): Date of the confirmation.
      - `distributorOrderNumber` (string): The distributor's order number.
      - `id` (integer): EGIS id of the confirmation.
      - `lines` (array of object): Confirmed lines.
        - `deliveryDate` (string (date)): Expected delivery date.
        - `position` (integer): Purchase order line.
        - `quantity` (number): Planned delivery quantity.
        - `supplierArticleNumber` (string): The distributor's article number.
        - `unitPrice` (number): Confirmed net unit price.
    - `deliveryNotes` (array of object): Delivery notes of the distributor.
      - `date` (string (date)): Date of the delivery note.
      - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
      - `id` (string): EGIS delivery note id.
      - `lines` (array of object): Delivered lines.
        - `description` (string): Description of the article.
        - `ean` (string): EAN (GTIN) of the article.
        - `mpn` (string): Manufacturer part number.
        - `position` (integer): Position number of the line.
        - `quantity` (number): Quantity delivered.
        - `serialNumbers` (array of string): Serial numbers.
        - `supplierArticleNumber` (string): The distributor's article number.
        - `unit` (string): Unit of measure.
      - `number` (string): The distributor's delivery note number.
      - `packages` (array of object): Packages of the shipment.
        - `number` (string): Tracking number of the package.
        - `trackingUrl` (string (uri)): Tracking link of the package.
      - `shipper` (string): Carrier of the shipment.
    - `distributorId` (string): EGIS distributor number.
    - `distributorName` (string): Name of the distributor the order went to.
    - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
    - `freightCharge` (number): Freight including additional charges.
    - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
      - `currency` (string): Currency (ISO 4217).
      - `date` (string (date)): Invoice date.
      - `grossAmount` (number): Gross amount of the invoice.
      - `id` (integer): EGIS id of the invoice.
      - `lines` (array of object): Invoiced lines.
        - `description` (string): Description of the article.
        - `netTotal` (number): Net total of the line.
        - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
        - `quantity` (number): Quantity invoiced.
        - `supplierArticleNumber` (string): The distributor's article number.
        - `taxRate` (number): Percent.
        - `unitPrice` (number): Net unit price.
      - `netAmount` (number): Net amount of the invoice.
      - `number` (string): The distributor's invoice number.
      - `vatAmount` (number): VAT amount of the invoice.
    - `link` (string (uri)): The order in the EGIS web application.
    - `orderDate` (string (date)): Order date at EGIS.
    - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
    - `paymentMethod` (string): Payment method of the order at EGIS.
    - `sentAt` (string (date-time)): When the order was sent to EGIS.
    - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
    - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
    - `statusText` (string): Status text of EGIS.
  - `goodsReceipts` (array of object): Goods receipts of the purchase order.
    - `grNumber` (string): Number of the goods receipt.
    - `id` (string (uuid)): Id of the goods receipt.
    - `receivedAt` (string (date-time)): When the goods were received.
    - `status` (string): Status of the goods receipt.
  - `id` (string (uuid)): Id of the purchase order.
  - `lines` (array of POLine): Empty in lists.
    - `articleNumber` (string): Article number in masterdata.
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `id` (string (uuid)): Id of the purchase order line.
    - `invoicedQty` (number): Always 0.
    - `mpn` (string): Manufacturer part number.
    - `orderedQty` (number): Quantity ordered.
    - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
    - `position` (integer): Position number of the line.
    - `productId` (string (uuid)): Masterdata article (product) id.
    - `receivedQty` (number): Quantity received.
    - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
    - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
  - `netTotal` (number): Net total of the purchase order.
  - `orderDate` (string (date)): Order date.
  - `poNumber` (string): Number of the purchase order.
  - `sourceOrders` (array of object): The sales orders the lines were bought for.
    - `id` (string (uuid)): Id of the sales order.
    - `number` (string): Number of the sales order.
  - `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
    - `cartId` (string (uuid)): Purchase cart the order was made from.
    - `distributorId` (string): Distributor the cart optimizer chose.
    - `goodsCents` (integer): Goods value of the shipment in cents.
    - `offerKey` (string): Key of the distributor offer.
    - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
    - `optimizedAt` (string (date-time)): When the proposal was computed.
    - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
    - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
    - `shippingCents` (integer): Shipping cost of the shipment in cents.
    - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
  - `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
  - `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
  - `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
    - `attemptedAt` (string (date-time)): When the last API send started.
    - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
    - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
    - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
    - `error` (string): Why the last send or refresh failed.
    - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
    - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
    - `invoices` (array of object): Invoices the supplier reported.
      - `date` (string (date)): Invoice date.
      - `grossTotal` (number): Gross total.
      - `netTotal` (number): Net total.
      - `number` (string): Invoice number of the supplier.
    - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
    - `lineMap` (object): Supplier line number → purchase order line id.
    - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
    - `recipient` (string (email)): Where the mail went (mail).
    - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `reason` (string): The supplier's reason.
      - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
    - `related` (array of string): Further order numbers when the supplier split the order.
    - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
    - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
    - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
    - `sentAt` (string (date-time)): When the order was sent.
    - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
    - `shipments` (array of object): Shipments the supplier reported.
      - `carrier` (string): Carrier of the shipment.
      - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
      - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
      - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
      - `invoiceNumber` (string): The supplier's invoice of the shipment.
      - `lines` (array of object): Lines of the shipment.
        - `lineId` (string (uuid)): Id of the purchase order line.
        - `quantity` (number): Quantity shipped.
        - `serialNumbers` (array of string): Serial numbers.
      - `number` (string): The supplier's delivery note number.
      - `shippedAt` (string (date-time)): When it was shipped.
      - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
      - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
      - `takeoverError` (string): Why the last hand-over failed.
      - `trackingNumber` (string): Tracking number of the carrier.
      - `trackingUrl` (string): Tracking link of the carrier.
    - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
    - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
    - `statusText` (string): The supplier's status text.
  - `updatedAt` (string (date-time)): When the purchase order was last changed.
- `total` (integer, required): Number of entries of the whole list.
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-17T10:05:00Z",
      "currency": "EUR",
      "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d71",
      "lines": [],
      "netTotal": 2180,
      "orderDate": "2026-11-17",
      "poNumber": "BE-2026-00071",
      "status": "open",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "updatedAt": "2026-11-17T10:12:00Z"
    },
    {
      "createdAt": "2026-11-13T09:12:00Z",
      "currency": "EUR",
      "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
      "lines": [],
      "netTotal": 481,
      "orderDate": "2026-11-13",
      "poNumber": "BE-2026-00068",
      "status": "open",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
      "updatedAt": "2026-11-13T09:20:00Z"
    }
  ],
  "nextCursor": "Y3JlYXRlZHwyMDI2LTExLTEzVDA5OjEyOjAwWnwxYjRjNWQ2ZS03ZjhhLTRiOWMtOGQwZS0yZjNhNGI1YzZkNjg",
  "total": 12
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/purchase-orders' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a purchase order (tenant:trade:purchasing:write)

`POST /api/trade/v1/purchase-orders`

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

`status` defaults to `open`; `supplierAddressId` (or the legacy `supplierId`) is required. Publishes `trade.purchaseorder.created`.

### Request body

`application/json` (required)

- `poNumber` (string, required): Number of the purchase order. (max length 64)
- `currency` (string): Currency (ISO 4217); EUR when empty.
- `lines` (array of POLineInput): Lines of the purchase order.
  - `description` (string, required): Description of the line. (max length 500)
  - `orderedQty` (number, required): Quantity ordered.
  - `articleNumber` (string): Article number in masterdata. (max length 100)
  - `ean` (string): EAN (GTIN) of the article. (max length 32)
  - `mpn` (string): Manufacturer part number. (max length 100)
  - `position` (integer): Unique within the order.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `taxRate` (number): Tax rate in percent. (max 100)
  - `unit` (string): Unit of measure. (max length 20)
  - `unitPrice` (number): Net unit price.
- `orderDate` (string (date)): Order date.
- `status` (string): Initial status (`draft` or `open`); `open` when empty. (one of `draft`, `open`; default `"open"`)
- `supplierAddressId` (string (uuid)): Required (or `supplierId`).
- `supplierId` (string (uuid)): Legacy name of `supplierAddressId`.

Example:

```json
{
  "currency": "EUR",
  "lines": [
    {
      "articleNumber": "LNVT14G5",
      "description": "Lenovo ThinkPad T14 Gen 5",
      "orderedQty": 5,
      "position": 1,
      "taxRate": 19,
      "unit": "Stk",
      "unitPrice": 1049
    }
  ],
  "orderDate": "2026-10-22",
  "poNumber": "BE-2026-0815",
  "supplierAddressId": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **409** The order number exists already. (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 201 answer:

- `createdAt` (string (date-time)): When the purchase order was created.
- `currency` (string): Currency (ISO 4217).
- `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
- `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
  - `cargoInsurance` (number): Cargo insurance charged.
  - `confirmations` (array of object): Order confirmations of the distributor.
    - `date` (string (date)): Date of the confirmation.
    - `distributorOrderNumber` (string): The distributor's order number.
    - `id` (integer): EGIS id of the confirmation.
    - `lines` (array of object): Confirmed lines.
      - `deliveryDate` (string (date)): Expected delivery date.
      - `position` (integer): Purchase order line.
      - `quantity` (number): Planned delivery quantity.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unitPrice` (number): Confirmed net unit price.
  - `deliveryNotes` (array of object): Delivery notes of the distributor.
    - `date` (string (date)): Date of the delivery note.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `id` (string): EGIS delivery note id.
    - `lines` (array of object): Delivered lines.
      - `description` (string): Description of the article.
      - `ean` (string): EAN (GTIN) of the article.
      - `mpn` (string): Manufacturer part number.
      - `position` (integer): Position number of the line.
      - `quantity` (number): Quantity delivered.
      - `serialNumbers` (array of string): Serial numbers.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unit` (string): Unit of measure.
    - `number` (string): The distributor's delivery note number.
    - `packages` (array of object): Packages of the shipment.
      - `number` (string): Tracking number of the package.
      - `trackingUrl` (string (uri)): Tracking link of the package.
    - `shipper` (string): Carrier of the shipment.
  - `distributorId` (string): EGIS distributor number.
  - `distributorName` (string): Name of the distributor the order went to.
  - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
  - `freightCharge` (number): Freight including additional charges.
  - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
    - `currency` (string): Currency (ISO 4217).
    - `date` (string (date)): Invoice date.
    - `grossAmount` (number): Gross amount of the invoice.
    - `id` (integer): EGIS id of the invoice.
    - `lines` (array of object): Invoiced lines.
      - `description` (string): Description of the article.
      - `netTotal` (number): Net total of the line.
      - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
      - `quantity` (number): Quantity invoiced.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `taxRate` (number): Percent.
      - `unitPrice` (number): Net unit price.
    - `netAmount` (number): Net amount of the invoice.
    - `number` (string): The distributor's invoice number.
    - `vatAmount` (number): VAT amount of the invoice.
  - `link` (string (uri)): The order in the EGIS web application.
  - `orderDate` (string (date)): Order date at EGIS.
  - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
  - `paymentMethod` (string): Payment method of the order at EGIS.
  - `sentAt` (string (date-time)): When the order was sent to EGIS.
  - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
  - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
  - `statusText` (string): Status text of EGIS.
- `goodsReceipts` (array of object): Goods receipts of the purchase order.
  - `grNumber` (string): Number of the goods receipt.
  - `id` (string (uuid)): Id of the goods receipt.
  - `receivedAt` (string (date-time)): When the goods were received.
  - `status` (string): Status of the goods receipt.
- `id` (string (uuid)): Id of the purchase order.
- `lines` (array of POLine): Empty in lists.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid)): Id of the purchase order line.
  - `invoicedQty` (number): Always 0.
  - `mpn` (string): Manufacturer part number.
  - `orderedQty` (number): Quantity ordered.
  - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
  - `position` (integer): Position number of the line.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `receivedQty` (number): Quantity received.
  - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
  - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
- `netTotal` (number): Net total of the purchase order.
- `orderDate` (string (date)): Order date.
- `poNumber` (string): Number of the purchase order.
- `sourceOrders` (array of object): The sales orders the lines were bought for.
  - `id` (string (uuid)): Id of the sales order.
  - `number` (string): Number of the sales order.
- `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
  - `cartId` (string (uuid)): Purchase cart the order was made from.
  - `distributorId` (string): Distributor the cart optimizer chose.
  - `goodsCents` (integer): Goods value of the shipment in cents.
  - `offerKey` (string): Key of the distributor offer.
  - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
  - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
  - `shippingCents` (integer): Shipping cost of the shipment in cents.
  - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
- `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
  - `attemptedAt` (string (date-time)): When the last API send started.
  - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
  - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
  - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
  - `error` (string): Why the last send or refresh failed.
  - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
  - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
  - `invoices` (array of object): Invoices the supplier reported.
    - `date` (string (date)): Invoice date.
    - `grossTotal` (number): Gross total.
    - `netTotal` (number): Net total.
    - `number` (string): Invoice number of the supplier.
  - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
  - `lineMap` (object): Supplier line number → purchase order line id.
  - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
  - `recipient` (string (email)): Where the mail went (mail).
  - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
    - `lineId` (string (uuid)): Id of the purchase order line.
    - `reason` (string): The supplier's reason.
    - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
  - `related` (array of string): Further order numbers when the supplier split the order.
  - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
  - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
  - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
  - `sentAt` (string (date-time)): When the order was sent.
  - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
  - `shipments` (array of object): Shipments the supplier reported.
    - `carrier` (string): Carrier of the shipment.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
    - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
    - `invoiceNumber` (string): The supplier's invoice of the shipment.
    - `lines` (array of object): Lines of the shipment.
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `quantity` (number): Quantity shipped.
      - `serialNumbers` (array of string): Serial numbers.
    - `number` (string): The supplier's delivery note number.
    - `shippedAt` (string (date-time)): When it was shipped.
    - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
    - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
    - `takeoverError` (string): Why the last hand-over failed.
    - `trackingNumber` (string): Tracking number of the carrier.
    - `trackingUrl` (string): Tracking link of the carrier.
  - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
  - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
  - `statusText` (string): The supplier's status text.
- `updatedAt` (string (date-time)): When the purchase order was last changed.

Example 201 answer:

```json
{
  "createdAt": "2026-10-22T08:30:00Z",
  "currency": "EUR",
  "goodsReceipts": [],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d15",
  "lines": [
    {
      "articleNumber": "LNVT14G5",
      "description": "Lenovo ThinkPad T14 Gen 5",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e31",
      "invoicedQty": 0,
      "orderedQty": 5,
      "position": 1,
      "receivedQty": 0,
      "taxRate": 19,
      "unit": "Stk",
      "unitPrice": 1049
    }
  ],
  "netTotal": 5245,
  "orderDate": "2026-10-22",
  "poNumber": "BE-2026-0815",
  "status": "open",
  "supplierAddressId": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "updatedAt": "2026-10-22T08:30:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"currency":"EUR","lines":[{"articleNumber":"LNVT14G5","description":"Lenovo ThinkPad T14 Gen 5","orderedQty":5,"position":1,"taxRate":19,"unit":"Stk","unitPrice":1049}],"orderDate":"2026-10-22","poNumber":"BE-2026-0815","supplierAddressId":"7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f"}'
```

## Get a purchase order with lines and goods receipts (tenant:trade:purchasing:read)

`GET /api/trade/v1/purchase-orders/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Purchase order (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the purchase order was created.
- `currency` (string): Currency (ISO 4217).
- `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
- `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
  - `cargoInsurance` (number): Cargo insurance charged.
  - `confirmations` (array of object): Order confirmations of the distributor.
    - `date` (string (date)): Date of the confirmation.
    - `distributorOrderNumber` (string): The distributor's order number.
    - `id` (integer): EGIS id of the confirmation.
    - `lines` (array of object): Confirmed lines.
      - `deliveryDate` (string (date)): Expected delivery date.
      - `position` (integer): Purchase order line.
      - `quantity` (number): Planned delivery quantity.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unitPrice` (number): Confirmed net unit price.
  - `deliveryNotes` (array of object): Delivery notes of the distributor.
    - `date` (string (date)): Date of the delivery note.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `id` (string): EGIS delivery note id.
    - `lines` (array of object): Delivered lines.
      - `description` (string): Description of the article.
      - `ean` (string): EAN (GTIN) of the article.
      - `mpn` (string): Manufacturer part number.
      - `position` (integer): Position number of the line.
      - `quantity` (number): Quantity delivered.
      - `serialNumbers` (array of string): Serial numbers.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unit` (string): Unit of measure.
    - `number` (string): The distributor's delivery note number.
    - `packages` (array of object): Packages of the shipment.
      - `number` (string): Tracking number of the package.
      - `trackingUrl` (string (uri)): Tracking link of the package.
    - `shipper` (string): Carrier of the shipment.
  - `distributorId` (string): EGIS distributor number.
  - `distributorName` (string): Name of the distributor the order went to.
  - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
  - `freightCharge` (number): Freight including additional charges.
  - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
    - `currency` (string): Currency (ISO 4217).
    - `date` (string (date)): Invoice date.
    - `grossAmount` (number): Gross amount of the invoice.
    - `id` (integer): EGIS id of the invoice.
    - `lines` (array of object): Invoiced lines.
      - `description` (string): Description of the article.
      - `netTotal` (number): Net total of the line.
      - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
      - `quantity` (number): Quantity invoiced.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `taxRate` (number): Percent.
      - `unitPrice` (number): Net unit price.
    - `netAmount` (number): Net amount of the invoice.
    - `number` (string): The distributor's invoice number.
    - `vatAmount` (number): VAT amount of the invoice.
  - `link` (string (uri)): The order in the EGIS web application.
  - `orderDate` (string (date)): Order date at EGIS.
  - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
  - `paymentMethod` (string): Payment method of the order at EGIS.
  - `sentAt` (string (date-time)): When the order was sent to EGIS.
  - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
  - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
  - `statusText` (string): Status text of EGIS.
- `goodsReceipts` (array of object): Goods receipts of the purchase order.
  - `grNumber` (string): Number of the goods receipt.
  - `id` (string (uuid)): Id of the goods receipt.
  - `receivedAt` (string (date-time)): When the goods were received.
  - `status` (string): Status of the goods receipt.
- `id` (string (uuid)): Id of the purchase order.
- `lines` (array of POLine): Empty in lists.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid)): Id of the purchase order line.
  - `invoicedQty` (number): Always 0.
  - `mpn` (string): Manufacturer part number.
  - `orderedQty` (number): Quantity ordered.
  - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
  - `position` (integer): Position number of the line.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `receivedQty` (number): Quantity received.
  - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
  - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
- `netTotal` (number): Net total of the purchase order.
- `orderDate` (string (date)): Order date.
- `poNumber` (string): Number of the purchase order.
- `sourceOrders` (array of object): The sales orders the lines were bought for.
  - `id` (string (uuid)): Id of the sales order.
  - `number` (string): Number of the sales order.
- `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
  - `cartId` (string (uuid)): Purchase cart the order was made from.
  - `distributorId` (string): Distributor the cart optimizer chose.
  - `goodsCents` (integer): Goods value of the shipment in cents.
  - `offerKey` (string): Key of the distributor offer.
  - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
  - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
  - `shippingCents` (integer): Shipping cost of the shipment in cents.
  - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
- `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
  - `attemptedAt` (string (date-time)): When the last API send started.
  - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
  - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
  - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
  - `error` (string): Why the last send or refresh failed.
  - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
  - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
  - `invoices` (array of object): Invoices the supplier reported.
    - `date` (string (date)): Invoice date.
    - `grossTotal` (number): Gross total.
    - `netTotal` (number): Net total.
    - `number` (string): Invoice number of the supplier.
  - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
  - `lineMap` (object): Supplier line number → purchase order line id.
  - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
  - `recipient` (string (email)): Where the mail went (mail).
  - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
    - `lineId` (string (uuid)): Id of the purchase order line.
    - `reason` (string): The supplier's reason.
    - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
  - `related` (array of string): Further order numbers when the supplier split the order.
  - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
  - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
  - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
  - `sentAt` (string (date-time)): When the order was sent.
  - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
  - `shipments` (array of object): Shipments the supplier reported.
    - `carrier` (string): Carrier of the shipment.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
    - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
    - `invoiceNumber` (string): The supplier's invoice of the shipment.
    - `lines` (array of object): Lines of the shipment.
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `quantity` (number): Quantity shipped.
      - `serialNumbers` (array of string): Serial numbers.
    - `number` (string): The supplier's delivery note number.
    - `shippedAt` (string (date-time)): When it was shipped.
    - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
    - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
    - `takeoverError` (string): Why the last hand-over failed.
    - `trackingNumber` (string): Tracking number of the carrier.
    - `trackingUrl` (string): Tracking link of the carrier.
  - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
  - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
  - `statusText` (string): The supplier's status text.
- `updatedAt` (string (date-time)): When the purchase order was last changed.

Example 200 answer:

```json
{
  "createdAt": "2026-11-13T09:12:00Z",
  "currency": "EUR",
  "goodsReceipts": [],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
      "invoicedQty": 0,
      "orderedQty": 1,
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "receivedQty": 0,
      "supplierArticleNumber": "KW-RACK12HE",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 289
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
      "invoicedQty": 0,
      "orderedQty": 3,
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "receivedQty": 0,
      "supplierArticleNumber": "KW-CAT7-100",
      "taxRate": 19,
      "unit": "PAK",
      "unitPrice": 64
    }
  ],
  "netTotal": 481,
  "orderDate": "2026-11-13",
  "poNumber": "BE-2026-00068",
  "status": "open",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierOrder": {
    "channel": "mail",
    "comment": "Bitte an den Wareneingang, Tor 2, liefern.",
    "recipient": "bestellung@kabelwerk-sued.example",
    "requestedDeliveryDate": "2026-11-20",
    "revision": 1,
    "sentAt": "2026-11-13T09:20:00Z",
    "state": "sent"
  },
  "updatedAt": "2026-11-13T09:20:00Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change a purchase order (tenant:trade:purchasing:write)

`PATCH /api/trade/v1/purchase-orders/{id}`

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

Only fields sent are changed. Closed and cancelled orders cannot be changed; `lines` replaces all lines and is only allowed while no goods were received (`409`). While a supplier API send of the order has no outcome yet or failed (`supplierOrder.state` `sending`, or `failed` through a distributor API), the order cannot be cancelled or closed and its lines cannot be replaced (`409`), because the distributor may hold it. Once an order went to a distributor API (`supplierOrder.channel` `ingram` or `infinigate`), its lines cannot be replaced at all (`409`; the supplier line map names the line ids). Orders sent through EGIS (`egis`, see `sendEgisOrder`) keep the EGIS rules, and their lines are not checked here. Publishes `trade.purchaseorder.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `currency` (string): Currency (ISO 4217).
- `lines` (array of POLineInput): Replaces all lines; only before goods were received.
  - `description` (string, required): Description of the line. (max length 500)
  - `orderedQty` (number, required): Quantity ordered.
  - `articleNumber` (string): Article number in masterdata. (max length 100)
  - `ean` (string): EAN (GTIN) of the article. (max length 32)
  - `mpn` (string): Manufacturer part number. (max length 100)
  - `position` (integer): Unique within the order.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `taxRate` (number): Tax rate in percent. (max 100)
  - `unit` (string): Unit of measure. (max length 20)
  - `unitPrice` (number): Net unit price.
- `orderDate` (string (date)): Order date.
- `status` (string): New status of the purchase order. (one of `draft`, `open`, `closed`, `cancelled`)

Example:

```json
{
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "orderedQty": 1,
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 289
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "orderedQty": 3,
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "taxRate": 19,
      "unit": "PAK",
      "unitPrice": 64
    }
  ],
  "orderDate": "2026-11-13",
  "status": "open"
}
```

### Responses

- **200** Updated (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** Error (`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 200 answer:

- `createdAt` (string (date-time)): When the purchase order was created.
- `currency` (string): Currency (ISO 4217).
- `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
- `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
  - `cargoInsurance` (number): Cargo insurance charged.
  - `confirmations` (array of object): Order confirmations of the distributor.
    - `date` (string (date)): Date of the confirmation.
    - `distributorOrderNumber` (string): The distributor's order number.
    - `id` (integer): EGIS id of the confirmation.
    - `lines` (array of object): Confirmed lines.
      - `deliveryDate` (string (date)): Expected delivery date.
      - `position` (integer): Purchase order line.
      - `quantity` (number): Planned delivery quantity.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unitPrice` (number): Confirmed net unit price.
  - `deliveryNotes` (array of object): Delivery notes of the distributor.
    - `date` (string (date)): Date of the delivery note.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `id` (string): EGIS delivery note id.
    - `lines` (array of object): Delivered lines.
      - `description` (string): Description of the article.
      - `ean` (string): EAN (GTIN) of the article.
      - `mpn` (string): Manufacturer part number.
      - `position` (integer): Position number of the line.
      - `quantity` (number): Quantity delivered.
      - `serialNumbers` (array of string): Serial numbers.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unit` (string): Unit of measure.
    - `number` (string): The distributor's delivery note number.
    - `packages` (array of object): Packages of the shipment.
      - `number` (string): Tracking number of the package.
      - `trackingUrl` (string (uri)): Tracking link of the package.
    - `shipper` (string): Carrier of the shipment.
  - `distributorId` (string): EGIS distributor number.
  - `distributorName` (string): Name of the distributor the order went to.
  - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
  - `freightCharge` (number): Freight including additional charges.
  - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
    - `currency` (string): Currency (ISO 4217).
    - `date` (string (date)): Invoice date.
    - `grossAmount` (number): Gross amount of the invoice.
    - `id` (integer): EGIS id of the invoice.
    - `lines` (array of object): Invoiced lines.
      - `description` (string): Description of the article.
      - `netTotal` (number): Net total of the line.
      - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
      - `quantity` (number): Quantity invoiced.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `taxRate` (number): Percent.
      - `unitPrice` (number): Net unit price.
    - `netAmount` (number): Net amount of the invoice.
    - `number` (string): The distributor's invoice number.
    - `vatAmount` (number): VAT amount of the invoice.
  - `link` (string (uri)): The order in the EGIS web application.
  - `orderDate` (string (date)): Order date at EGIS.
  - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
  - `paymentMethod` (string): Payment method of the order at EGIS.
  - `sentAt` (string (date-time)): When the order was sent to EGIS.
  - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
  - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
  - `statusText` (string): Status text of EGIS.
- `goodsReceipts` (array of object): Goods receipts of the purchase order.
  - `grNumber` (string): Number of the goods receipt.
  - `id` (string (uuid)): Id of the goods receipt.
  - `receivedAt` (string (date-time)): When the goods were received.
  - `status` (string): Status of the goods receipt.
- `id` (string (uuid)): Id of the purchase order.
- `lines` (array of POLine): Empty in lists.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid)): Id of the purchase order line.
  - `invoicedQty` (number): Always 0.
  - `mpn` (string): Manufacturer part number.
  - `orderedQty` (number): Quantity ordered.
  - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
  - `position` (integer): Position number of the line.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `receivedQty` (number): Quantity received.
  - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
  - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
- `netTotal` (number): Net total of the purchase order.
- `orderDate` (string (date)): Order date.
- `poNumber` (string): Number of the purchase order.
- `sourceOrders` (array of object): The sales orders the lines were bought for.
  - `id` (string (uuid)): Id of the sales order.
  - `number` (string): Number of the sales order.
- `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
  - `cartId` (string (uuid)): Purchase cart the order was made from.
  - `distributorId` (string): Distributor the cart optimizer chose.
  - `goodsCents` (integer): Goods value of the shipment in cents.
  - `offerKey` (string): Key of the distributor offer.
  - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
  - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
  - `shippingCents` (integer): Shipping cost of the shipment in cents.
  - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
- `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
  - `attemptedAt` (string (date-time)): When the last API send started.
  - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
  - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
  - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
  - `error` (string): Why the last send or refresh failed.
  - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
  - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
  - `invoices` (array of object): Invoices the supplier reported.
    - `date` (string (date)): Invoice date.
    - `grossTotal` (number): Gross total.
    - `netTotal` (number): Net total.
    - `number` (string): Invoice number of the supplier.
  - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
  - `lineMap` (object): Supplier line number → purchase order line id.
  - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
  - `recipient` (string (email)): Where the mail went (mail).
  - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
    - `lineId` (string (uuid)): Id of the purchase order line.
    - `reason` (string): The supplier's reason.
    - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
  - `related` (array of string): Further order numbers when the supplier split the order.
  - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
  - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
  - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
  - `sentAt` (string (date-time)): When the order was sent.
  - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
  - `shipments` (array of object): Shipments the supplier reported.
    - `carrier` (string): Carrier of the shipment.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
    - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
    - `invoiceNumber` (string): The supplier's invoice of the shipment.
    - `lines` (array of object): Lines of the shipment.
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `quantity` (number): Quantity shipped.
      - `serialNumbers` (array of string): Serial numbers.
    - `number` (string): The supplier's delivery note number.
    - `shippedAt` (string (date-time)): When it was shipped.
    - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
    - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
    - `takeoverError` (string): Why the last hand-over failed.
    - `trackingNumber` (string): Tracking number of the carrier.
    - `trackingUrl` (string): Tracking link of the carrier.
  - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
  - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
  - `statusText` (string): The supplier's status text.
- `updatedAt` (string (date-time)): When the purchase order was last changed.

Example 200 answer:

```json
{
  "createdAt": "2026-11-13T09:12:00Z",
  "currency": "EUR",
  "goodsReceipts": [],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
      "invoicedQty": 0,
      "orderedQty": 1,
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "receivedQty": 0,
      "supplierArticleNumber": "KW-RACK12HE",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 289
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
      "invoicedQty": 0,
      "orderedQty": 3,
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "receivedQty": 0,
      "supplierArticleNumber": "KW-CAT7-100",
      "taxRate": 19,
      "unit": "PAK",
      "unitPrice": 64
    }
  ],
  "netTotal": 481,
  "orderDate": "2026-11-13",
  "poNumber": "BE-2026-00068",
  "status": "open",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierOrder": {
    "channel": "mail",
    "comment": "Bitte an den Wareneingang, Tor 2, liefern.",
    "recipient": "bestellung@kabelwerk-sued.example",
    "requestedDeliveryDate": "2026-11-20",
    "revision": 1,
    "sentAt": "2026-11-13T09:20:00Z",
    "state": "sent"
  },
  "updatedAt": "2026-11-13T09:20:00Z"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"lines":[{"articleNumber":"NW-2004","description":"Netzwerkschrank 19 Zoll 12 HE","orderedQty":1,"position":1,"productId":"4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04","taxRate":19,"unit":"STK","unitPrice":289},{"articleNumber":"NW-2005","description":"Verlegekabel Cat.7 Simplex, 100 m","orderedQty":3,"position":2,"productId":"4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05","taxRate":19,"unit":"PAK","unitPrice":64}],"orderDate":"2026-11-13","status":"open"}'
```

## Check a purchase order before sending it through EGIS (tenant:egis-order:send)

`POST /api/trade/v1/purchase-orders/{id}/egis/preview`

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

Resolves the EGIS distributor of the order's supplier (ITSP settings › EGIS suppliers) and every line in EGIS
(price and availability by PCS number, else EAN): the distributor's article number, the article types and the
current EGIS price. Names what EGIS still needs – a supplier without EGIS distributor, missing distributor article
numbers, whole quantities, the customer's e-mail for ESD articles (types `ESD`, `WVL`), licence data (`LIC`, `HLI`,
`EHV`, `EHS`) and serial numbers with purchase date (`CPS`, `EHS`). Sends nothing. The body is optional.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `comment` (string): Order remark; EGIS requires it when a price deviates from the EGIS price. (max length 200)
- `completeShipment` (boolean): Complete delivery wanted (supported by some distributors).
- `licence` (EgisLicenceData): One set of licence data per order (articles of the types LIC, HLI, EHV, EHS; serial numbers and purchase date for CPS and EHS). Which fields a distributor needs depends on the distributor and the article.
  - `authorizationNumber` (string): Authorization number of the licence.
  - `authorizationValidFrom` (string (date)): First day of the authorization.
  - `authorizationValidTo` (string (date)): Last day of the authorization.
  - `city` (string): City.
  - `contactName` (string): Name of the contact person.
  - `countryCode` (string): Country code (ISO 3166-1 alpha-2). (max length 2)
  - `domain` (string): Domain of the licensee.
  - `email` (string): E-mail address.
  - `name` (string): Name of the licensee.
  - `phone` (string): Phone number.
  - `postalCode` (string): Postal code.
  - `purchaseDate` (string (date)): Purchase date of the licence.
  - `resellerEmail` (string): E-mail of the reseller.
  - `serialNumbers` (string): Separated by semicolons.
  - `street` (string): Street and house number.
- `lines` (array of object): Completes purchase order lines; lines not named are resolved in EGIS.
  - `lineId` (string (uuid), required): Id of the purchase order line.
  - `customerEmail` (string (email)): Required for ESD articles. (max length 50)
  - `pcsNumber` (string): EGIS article number (PCS). (max length 10)
  - `supplierArticleNumber` (string): The distributor's article number (else found in EGIS). (max length 25)
- `requestedDeliveryDate` (string (date)): Requested delivery date.

Example:

```json
{
  "comment": "Bitte Lieferung an Tor 2.",
  "completeShipment": true,
  "lines": [
    {
      "lineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e11",
      "pcsNumber": "PCS400935"
    },
    {
      "lineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e12",
      "pcsNumber": "PCS400942"
    }
  ],
  "requestedDeliveryDate": "2026-11-19"
}
```

### Responses

- **200** What would be sent (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** Sent already (also by mail, recorded by hand or through a distributor API, unless that send failed), or not a draft or open order. (`application/json`)
- **422** EGIS is not set up for the tenant. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `distributorId` (string): EGIS id of the distributor the order goes to.
- `distributorName` (string): Name of the distributor the order goes to.
- `lines` (array of object): The purchase order lines as EGIS will get them.
  - `customerEmail` (string): E-mail of the end customer (ESD articles).
  - `description` (string): Description of the line.
  - `egisPrice` (number): The distributor's current purchase price in EGIS.
  - `lineId` (string (uuid)): Id of the purchase order line.
  - `needsCustomerEmail` (boolean): The article needs the e-mail of the end customer.
  - `pcsNumber` (string): EGIS PCS article number.
  - `position` (integer): Position number of the line.
  - `problems` (array of string): What is missing for the line.
  - `productTypes` (array of string): EGIS product types of the article (e.g. `ESD`).
  - `quantity` (number): Quantity.
  - `supplierArticleNumber` (string): The distributor's article number.
  - `unitPrice` (number): Net unit price.
- `needsLicence` (boolean): The order needs licence data (`licence` in the send request).
- `needsSerialNumbers` (boolean): The order needs serial numbers of the devices.
- `problems` (array of string): German texts of what the order lacks.
- `ready` (boolean): Nothing is missing; the order can be sent.

Example 200 answer:

```json
{
  "distributorId": "70044",
  "distributorName": "Nordlicht IT-Distribution GmbH",
  "lines": [
    {
      "description": "USB-C Dockingstation 100 W",
      "egisPrice": 139,
      "lineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e11",
      "needsCustomerEmail": false,
      "pcsNumber": "PCS400935",
      "position": 1,
      "problems": [],
      "productTypes": [
        "HW"
      ],
      "quantity": 10,
      "supplierArticleNumber": "NL-DOCKC100",
      "unitPrice": 139
    },
    {
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "egisPrice": 79,
      "lineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e12",
      "needsCustomerEmail": false,
      "pcsNumber": "PCS400942",
      "position": 2,
      "problems": [],
      "productTypes": [
        "HW"
      ],
      "quantity": 10,
      "supplierArticleNumber": "NL-HS-USB-ANC",
      "unitPrice": 79
    }
  ],
  "needsLicence": false,
  "needsSerialNumbers": false,
  "problems": [],
  "ready": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/egis/preview' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"comment":"Bitte Lieferung an Tor 2.","completeShipment":true,"lines":[{"lineId":"2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e11","pcsNumber":"PCS400935"},{"lineId":"2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e12","pcsNumber":"PCS400942"}],"requestedDeliveryDate":"2026-11-19"}'
```

## Send a purchase order to its distributor through EGIS (tenant:egis-order:send)

`POST /api/trade/v1/purchase-orders/{id}/egis`

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

Orders at the distributor through EGIS (always an online order, transmitted to the distributor). The order number
goes to EGIS as partner order number, which EGIS accepts once: an order is sent at most once, and a send whose
answer got lost is repaired by sending again (EGIS answers that it knows the number, the order is looked up and
stored). The EGIS order number and status are stored at the order (`egis`); a draft becomes `open`. The status,
confirmations, delivery notes and invoices are then followed every 30 minutes; delivery notes go to the delivery
note processing (`inbound-delivery-notes`, source `egis`). An order that lacks data is answered `422` with the
preview; an order locked by a running workflow (e.g. an approval) is not sent (`423`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `comment` (string): Order remark; EGIS requires it when a price deviates from the EGIS price. (max length 200)
- `completeShipment` (boolean): Complete delivery wanted (supported by some distributors).
- `licence` (EgisLicenceData): One set of licence data per order (articles of the types LIC, HLI, EHV, EHS; serial numbers and purchase date for CPS and EHS). Which fields a distributor needs depends on the distributor and the article.
  - `authorizationNumber` (string): Authorization number of the licence.
  - `authorizationValidFrom` (string (date)): First day of the authorization.
  - `authorizationValidTo` (string (date)): Last day of the authorization.
  - `city` (string): City.
  - `contactName` (string): Name of the contact person.
  - `countryCode` (string): Country code (ISO 3166-1 alpha-2). (max length 2)
  - `domain` (string): Domain of the licensee.
  - `email` (string): E-mail address.
  - `name` (string): Name of the licensee.
  - `phone` (string): Phone number.
  - `postalCode` (string): Postal code.
  - `purchaseDate` (string (date)): Purchase date of the licence.
  - `resellerEmail` (string): E-mail of the reseller.
  - `serialNumbers` (string): Separated by semicolons.
  - `street` (string): Street and house number.
- `lines` (array of object): Completes purchase order lines; lines not named are resolved in EGIS.
  - `lineId` (string (uuid), required): Id of the purchase order line.
  - `customerEmail` (string (email)): Required for ESD articles. (max length 50)
  - `pcsNumber` (string): EGIS article number (PCS). (max length 10)
  - `supplierArticleNumber` (string): The distributor's article number (else found in EGIS). (max length 25)
- `requestedDeliveryDate` (string (date)): Requested delivery date.

Example:

```json
{
  "comment": "Lieferung bitte an Lager 2",
  "completeShipment": false,
  "lines": [
    {
      "customerEmail": "it@kunde.example",
      "lineId": "3f2b8e8a-1c4d-4f7e-9a0b-2c3d4e5f6a7b"
    }
  ]
}
```

### Responses

- **200** Sent (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** Sent already (also by mail, recorded by hand or through a distributor API, unless that send failed), or not a draft or open order. (`application/json`)
- **422** EGIS is not set up (`egis_not_available`), or the order lacks data EGIS needs (`not_ready`, `details.preview` names it). (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the purchase order was created.
- `currency` (string): Currency (ISO 4217).
- `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
- `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
  - `cargoInsurance` (number): Cargo insurance charged.
  - `confirmations` (array of object): Order confirmations of the distributor.
    - `date` (string (date)): Date of the confirmation.
    - `distributorOrderNumber` (string): The distributor's order number.
    - `id` (integer): EGIS id of the confirmation.
    - `lines` (array of object): Confirmed lines.
      - `deliveryDate` (string (date)): Expected delivery date.
      - `position` (integer): Purchase order line.
      - `quantity` (number): Planned delivery quantity.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unitPrice` (number): Confirmed net unit price.
  - `deliveryNotes` (array of object): Delivery notes of the distributor.
    - `date` (string (date)): Date of the delivery note.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `id` (string): EGIS delivery note id.
    - `lines` (array of object): Delivered lines.
      - `description` (string): Description of the article.
      - `ean` (string): EAN (GTIN) of the article.
      - `mpn` (string): Manufacturer part number.
      - `position` (integer): Position number of the line.
      - `quantity` (number): Quantity delivered.
      - `serialNumbers` (array of string): Serial numbers.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unit` (string): Unit of measure.
    - `number` (string): The distributor's delivery note number.
    - `packages` (array of object): Packages of the shipment.
      - `number` (string): Tracking number of the package.
      - `trackingUrl` (string (uri)): Tracking link of the package.
    - `shipper` (string): Carrier of the shipment.
  - `distributorId` (string): EGIS distributor number.
  - `distributorName` (string): Name of the distributor the order went to.
  - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
  - `freightCharge` (number): Freight including additional charges.
  - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
    - `currency` (string): Currency (ISO 4217).
    - `date` (string (date)): Invoice date.
    - `grossAmount` (number): Gross amount of the invoice.
    - `id` (integer): EGIS id of the invoice.
    - `lines` (array of object): Invoiced lines.
      - `description` (string): Description of the article.
      - `netTotal` (number): Net total of the line.
      - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
      - `quantity` (number): Quantity invoiced.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `taxRate` (number): Percent.
      - `unitPrice` (number): Net unit price.
    - `netAmount` (number): Net amount of the invoice.
    - `number` (string): The distributor's invoice number.
    - `vatAmount` (number): VAT amount of the invoice.
  - `link` (string (uri)): The order in the EGIS web application.
  - `orderDate` (string (date)): Order date at EGIS.
  - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
  - `paymentMethod` (string): Payment method of the order at EGIS.
  - `sentAt` (string (date-time)): When the order was sent to EGIS.
  - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
  - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
  - `statusText` (string): Status text of EGIS.
- `goodsReceipts` (array of object): Goods receipts of the purchase order.
  - `grNumber` (string): Number of the goods receipt.
  - `id` (string (uuid)): Id of the goods receipt.
  - `receivedAt` (string (date-time)): When the goods were received.
  - `status` (string): Status of the goods receipt.
- `id` (string (uuid)): Id of the purchase order.
- `lines` (array of POLine): Empty in lists.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid)): Id of the purchase order line.
  - `invoicedQty` (number): Always 0.
  - `mpn` (string): Manufacturer part number.
  - `orderedQty` (number): Quantity ordered.
  - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
  - `position` (integer): Position number of the line.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `receivedQty` (number): Quantity received.
  - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
  - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
- `netTotal` (number): Net total of the purchase order.
- `orderDate` (string (date)): Order date.
- `poNumber` (string): Number of the purchase order.
- `sourceOrders` (array of object): The sales orders the lines were bought for.
  - `id` (string (uuid)): Id of the sales order.
  - `number` (string): Number of the sales order.
- `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
  - `cartId` (string (uuid)): Purchase cart the order was made from.
  - `distributorId` (string): Distributor the cart optimizer chose.
  - `goodsCents` (integer): Goods value of the shipment in cents.
  - `offerKey` (string): Key of the distributor offer.
  - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
  - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
  - `shippingCents` (integer): Shipping cost of the shipment in cents.
  - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
- `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
  - `attemptedAt` (string (date-time)): When the last API send started.
  - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
  - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
  - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
  - `error` (string): Why the last send or refresh failed.
  - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
  - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
  - `invoices` (array of object): Invoices the supplier reported.
    - `date` (string (date)): Invoice date.
    - `grossTotal` (number): Gross total.
    - `netTotal` (number): Net total.
    - `number` (string): Invoice number of the supplier.
  - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
  - `lineMap` (object): Supplier line number → purchase order line id.
  - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
  - `recipient` (string (email)): Where the mail went (mail).
  - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
    - `lineId` (string (uuid)): Id of the purchase order line.
    - `reason` (string): The supplier's reason.
    - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
  - `related` (array of string): Further order numbers when the supplier split the order.
  - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
  - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
  - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
  - `sentAt` (string (date-time)): When the order was sent.
  - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
  - `shipments` (array of object): Shipments the supplier reported.
    - `carrier` (string): Carrier of the shipment.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
    - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
    - `invoiceNumber` (string): The supplier's invoice of the shipment.
    - `lines` (array of object): Lines of the shipment.
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `quantity` (number): Quantity shipped.
      - `serialNumbers` (array of string): Serial numbers.
    - `number` (string): The supplier's delivery note number.
    - `shippedAt` (string (date-time)): When it was shipped.
    - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
    - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
    - `takeoverError` (string): Why the last hand-over failed.
    - `trackingNumber` (string): Tracking number of the carrier.
    - `trackingUrl` (string): Tracking link of the carrier.
  - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
  - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
  - `statusText` (string): The supplier's status text.
- `updatedAt` (string (date-time)): When the purchase order was last changed.

Example 200 answer:

```json
{
  "createdAt": "2026-11-17T10:05:00Z",
  "currency": "EUR",
  "egis": {
    "confirmations": [],
    "deliveryNotes": [],
    "distributorId": "70044",
    "distributorName": "Nordlicht IT-Distribution GmbH",
    "freightCharge": 0,
    "invoices": [],
    "link": "https://egis.example/bestellungen/0000733548",
    "orderDate": "2026-11-17",
    "orderNumber": "0000733548",
    "paymentMethod": "Rechnung",
    "sentAt": "2026-11-17T10:12:00Z",
    "statusCode": 10,
    "statusText": "An Distributor übermittelt"
  },
  "goodsReceipts": [],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d71",
  "lines": [
    {
      "articleNumber": "HW-1004",
      "description": "USB-C Dockingstation 100 W",
      "ean": "4061234500045",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e11",
      "invoicedQty": 0,
      "orderedQty": 10,
      "pcsNumber": "PCS400935",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
      "receivedQty": 0,
      "supplierArticleNumber": "NL-DOCKC100",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 139
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e12",
      "invoicedQty": 0,
      "orderedQty": 10,
      "pcsNumber": "PCS400942",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "receivedQty": 0,
      "supplierArticleNumber": "NL-HS-USB-ANC",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 79
    }
  ],
  "netTotal": 2180,
  "orderDate": "2026-11-17",
  "poNumber": "BE-2026-00071",
  "status": "open",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "updatedAt": "2026-11-17T10:12:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/egis' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"comment":"Lieferung bitte an Lager 2","completeShipment":false,"lines":[{"customerEmail":"it@kunde.example","lineId":"3f2b8e8a-1c4d-4f7e-9a0b-2c3d4e5f6a7b"}]}'
```

## Read the EGIS state of a sent purchase order now (tenant:egis-order:send)

`POST /api/trade/v1/purchase-orders/{id}/egis/refresh`

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

Status, confirmations, delivery notes and invoices from EGIS, instead of waiting for the next run (every 30 minutes). New delivery notes go to the delivery note processing; new invoice data checks the order's inbound invoices again.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The order with its EGIS state (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **422** Not sent through EGIS, or EGIS is not set up. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the purchase order was created.
- `currency` (string): Currency (ISO 4217).
- `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
- `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
  - `cargoInsurance` (number): Cargo insurance charged.
  - `confirmations` (array of object): Order confirmations of the distributor.
    - `date` (string (date)): Date of the confirmation.
    - `distributorOrderNumber` (string): The distributor's order number.
    - `id` (integer): EGIS id of the confirmation.
    - `lines` (array of object): Confirmed lines.
      - `deliveryDate` (string (date)): Expected delivery date.
      - `position` (integer): Purchase order line.
      - `quantity` (number): Planned delivery quantity.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unitPrice` (number): Confirmed net unit price.
  - `deliveryNotes` (array of object): Delivery notes of the distributor.
    - `date` (string (date)): Date of the delivery note.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `id` (string): EGIS delivery note id.
    - `lines` (array of object): Delivered lines.
      - `description` (string): Description of the article.
      - `ean` (string): EAN (GTIN) of the article.
      - `mpn` (string): Manufacturer part number.
      - `position` (integer): Position number of the line.
      - `quantity` (number): Quantity delivered.
      - `serialNumbers` (array of string): Serial numbers.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unit` (string): Unit of measure.
    - `number` (string): The distributor's delivery note number.
    - `packages` (array of object): Packages of the shipment.
      - `number` (string): Tracking number of the package.
      - `trackingUrl` (string (uri)): Tracking link of the package.
    - `shipper` (string): Carrier of the shipment.
  - `distributorId` (string): EGIS distributor number.
  - `distributorName` (string): Name of the distributor the order went to.
  - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
  - `freightCharge` (number): Freight including additional charges.
  - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
    - `currency` (string): Currency (ISO 4217).
    - `date` (string (date)): Invoice date.
    - `grossAmount` (number): Gross amount of the invoice.
    - `id` (integer): EGIS id of the invoice.
    - `lines` (array of object): Invoiced lines.
      - `description` (string): Description of the article.
      - `netTotal` (number): Net total of the line.
      - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
      - `quantity` (number): Quantity invoiced.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `taxRate` (number): Percent.
      - `unitPrice` (number): Net unit price.
    - `netAmount` (number): Net amount of the invoice.
    - `number` (string): The distributor's invoice number.
    - `vatAmount` (number): VAT amount of the invoice.
  - `link` (string (uri)): The order in the EGIS web application.
  - `orderDate` (string (date)): Order date at EGIS.
  - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
  - `paymentMethod` (string): Payment method of the order at EGIS.
  - `sentAt` (string (date-time)): When the order was sent to EGIS.
  - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
  - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
  - `statusText` (string): Status text of EGIS.
- `goodsReceipts` (array of object): Goods receipts of the purchase order.
  - `grNumber` (string): Number of the goods receipt.
  - `id` (string (uuid)): Id of the goods receipt.
  - `receivedAt` (string (date-time)): When the goods were received.
  - `status` (string): Status of the goods receipt.
- `id` (string (uuid)): Id of the purchase order.
- `lines` (array of POLine): Empty in lists.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid)): Id of the purchase order line.
  - `invoicedQty` (number): Always 0.
  - `mpn` (string): Manufacturer part number.
  - `orderedQty` (number): Quantity ordered.
  - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
  - `position` (integer): Position number of the line.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `receivedQty` (number): Quantity received.
  - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
  - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
- `netTotal` (number): Net total of the purchase order.
- `orderDate` (string (date)): Order date.
- `poNumber` (string): Number of the purchase order.
- `sourceOrders` (array of object): The sales orders the lines were bought for.
  - `id` (string (uuid)): Id of the sales order.
  - `number` (string): Number of the sales order.
- `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
  - `cartId` (string (uuid)): Purchase cart the order was made from.
  - `distributorId` (string): Distributor the cart optimizer chose.
  - `goodsCents` (integer): Goods value of the shipment in cents.
  - `offerKey` (string): Key of the distributor offer.
  - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
  - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
  - `shippingCents` (integer): Shipping cost of the shipment in cents.
  - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
- `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
  - `attemptedAt` (string (date-time)): When the last API send started.
  - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
  - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
  - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
  - `error` (string): Why the last send or refresh failed.
  - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
  - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
  - `invoices` (array of object): Invoices the supplier reported.
    - `date` (string (date)): Invoice date.
    - `grossTotal` (number): Gross total.
    - `netTotal` (number): Net total.
    - `number` (string): Invoice number of the supplier.
  - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
  - `lineMap` (object): Supplier line number → purchase order line id.
  - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
  - `recipient` (string (email)): Where the mail went (mail).
  - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
    - `lineId` (string (uuid)): Id of the purchase order line.
    - `reason` (string): The supplier's reason.
    - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
  - `related` (array of string): Further order numbers when the supplier split the order.
  - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
  - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
  - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
  - `sentAt` (string (date-time)): When the order was sent.
  - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
  - `shipments` (array of object): Shipments the supplier reported.
    - `carrier` (string): Carrier of the shipment.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
    - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
    - `invoiceNumber` (string): The supplier's invoice of the shipment.
    - `lines` (array of object): Lines of the shipment.
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `quantity` (number): Quantity shipped.
      - `serialNumbers` (array of string): Serial numbers.
    - `number` (string): The supplier's delivery note number.
    - `shippedAt` (string (date-time)): When it was shipped.
    - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
    - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
    - `takeoverError` (string): Why the last hand-over failed.
    - `trackingNumber` (string): Tracking number of the carrier.
    - `trackingUrl` (string): Tracking link of the carrier.
  - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
  - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
  - `statusText` (string): The supplier's status text.
- `updatedAt` (string (date-time)): When the purchase order was last changed.

Example 200 answer:

```json
{
  "createdAt": "2026-11-17T10:05:00Z",
  "currency": "EUR",
  "egis": {
    "confirmations": [
      {
        "date": "2026-11-17",
        "distributorOrderNumber": "NL-AB-2611-0457",
        "id": 918273,
        "lines": [
          {
            "deliveryDate": "2026-11-19",
            "position": 1,
            "quantity": 10,
            "supplierArticleNumber": "NL-DOCKC100",
            "unitPrice": 139
          },
          {
            "deliveryDate": "2026-11-19",
            "position": 2,
            "quantity": 10,
            "supplierArticleNumber": "NL-HS-USB-ANC",
            "unitPrice": 79
          }
        ]
      }
    ],
    "deliveryNotes": [],
    "distributorId": "70044",
    "distributorName": "Nordlicht IT-Distribution GmbH",
    "distributorOrderNumber": "NL-AB-2611-0457",
    "freightCharge": 0,
    "invoices": [],
    "link": "https://egis.example/bestellungen/0000733548",
    "orderDate": "2026-11-17",
    "orderNumber": "0000733548",
    "paymentMethod": "Rechnung",
    "sentAt": "2026-11-17T10:12:00Z",
    "statusCode": 30,
    "statusText": "Bestätigt"
  },
  "goodsReceipts": [],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d71",
  "lines": [
    {
      "articleNumber": "HW-1004",
      "description": "USB-C Dockingstation 100 W",
      "ean": "4061234500045",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e11",
      "invoicedQty": 0,
      "orderedQty": 10,
      "pcsNumber": "PCS400935",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d04",
      "receivedQty": 0,
      "supplierArticleNumber": "NL-DOCKC100",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 139
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e12",
      "invoicedQty": 0,
      "orderedQty": 10,
      "pcsNumber": "PCS400942",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "receivedQty": 0,
      "supplierArticleNumber": "NL-HS-USB-ANC",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 79
    }
  ],
  "netTotal": 2180,
  "orderDate": "2026-11-17",
  "poNumber": "BE-2026-00071",
  "status": "open",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
  "updatedAt": "2026-11-18T06:00:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/egis/refresh' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Show how a purchase order goes to its supplier (tenant:purchase-order:send)

`GET /api/trade/v1/purchase-orders/{id}/ordering`

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

The channel chosen from the supplier's masterdata distributor links and the tenant's connector settings, in the
order `egis` (EGIS set up) → `ingram` (ordering switched on) → `infinigate` (not available yet) → `mail` (the
supplier has an order mail address, `purchaseOrderEmail`, else `email`) → `manual`, and the channels the person may
switch to. An order made for a distributor by the cart optimizer prefers that distributor. Sends nothing. Masterdata
failing while the supplier is looked up is answered `502` (also by the preview, send and resend).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The channel (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `available` (array of string): Channels that can send the order, in the order of preference; always ends with `manual`.
- `channel` (string): The chosen channel; `egis` is sent with `sendEgisOrder`. (one of `egis`, `ingram`, `infinigate`, `mail`, `manual`)
- `distributorId` (string): The supplier's id at the chosen API channel's distributor.
- `recipient` (string (email)): The supplier's order mail address (`purchaseOrderEmail`, else `email`).

Example 200 answer:

```json
{
  "available": [
    "mail",
    "manual"
  ],
  "channel": "mail",
  "recipient": "bestellung@kabelwerk-sued.example"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/ordering' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Check a purchase order before sending it to its supplier (tenant:purchase-order:send)

`POST /api/trade/v1/purchase-orders/{id}/send/preview`

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

What the chosen channel (`channel`, else the resolved one) would send and what is missing, e.g. the recipient of
a mail. Sends nothing. The body is optional. A supplier ordered through EGIS is answered `409` with the EGIS route
(`route`): EGIS orders are checked and sent with `previewEgisOrder` / `sendEgisOrder`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `channel` (string): Another available channel than the resolved one; `mail` also with only a `recipient`. (one of `ingram`, `infinigate`, `mail`, `manual`)
- `comment` (string): Remark for the supplier. (max length 500)
- `externalOrderNumber` (string): Manual only: the supplier's order number. (max length 64)
- `recipient` (string (email)): Mail only: overrides the supplier's order mail address. (max length 254)
- `requestedDeliveryDate` (string (date)): Requested delivery date.

Example:

```json
{
  "channel": "mail",
  "comment": "Bitte an den Wareneingang, Tor 2, liefern.",
  "requestedDeliveryDate": "2026-11-20"
}
```

### Responses

- **200** What would be sent (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** A supplier ordered through EGIS is answered with `code` `use_egis`, `details.channel` `egis` and the EGIS route (`details.route`) – EGIS orders keep their own routes and permission. (`application/json`)
- **422** The channel is not available for the supplier, or the supplier is no longer in masterdata (German text). (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `channel` (string): Channel the order goes out by (`ingram`, `infinigate`, `mail` or `manual`). (one of `ingram`, `infinigate`, `mail`, `manual`)
- `lines` (array of object): The purchase order lines as the supplier will get them.
  - `description` (string): Description of the line.
  - `lineId` (string (uuid)): Id of the purchase order line.
  - `position` (integer): Position number of the line.
  - `problems` (array of string): What is missing for the line.
  - `quantity` (number): Quantity.
  - `supplierArticleNumber` (string): The number the supplier gets (mail: the manufacturer part number, else the article number; Ingram: the Ingram part number found by manufacturer part number, else EAN).
  - `supplierPrice` (number): The supplier's current price (API channels).
  - `unitPrice` (number): Net unit price.
  - `warnings` (array of string): Hints that do not keep the order from being sent, e.g. a supplier price that differs (Ingram).
- `problems` (array of string): German texts of what the order lacks.
- `ready` (boolean): Nothing is missing; the order can be sent.
- `recipient` (string (email)): Where the mail would go (mail).

Example 200 answer:

```json
{
  "channel": "mail",
  "lines": [
    {
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "lineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
      "position": 1,
      "problems": [],
      "quantity": 1,
      "supplierArticleNumber": "KW-RACK12HE",
      "unitPrice": 289,
      "warnings": []
    },
    {
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "lineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
      "position": 2,
      "problems": [],
      "quantity": 3,
      "supplierArticleNumber": "KW-CAT7-100",
      "unitPrice": 64,
      "warnings": []
    }
  ],
  "problems": [],
  "ready": true,
  "recipient": "bestellung@kabelwerk-sued.example"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/send/preview' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"channel":"mail","comment":"Bitte an den Wareneingang, Tor 2, liefern.","requestedDeliveryDate":"2026-11-20"}'
```

## Send a purchase order to its supplier (tenant:purchase-order:send)

`POST /api/trade/v1/purchase-orders/{id}/send`

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

Sends the order once through the chosen channel (`channel`, else the resolved one; see `getPurchaseOrderOrdering`):
`mail` mails it from the tenant's mailbox (the trade mail channel, else the tenant's default e-mail channel) to
`recipient` or the supplier's order mail address – the state and the mail commit together (idempotency key
`trade.purchase_order_supplier:<id>:<revision>`); `ingram` orders through the Ingram Micro reseller API (ordering
switched on in the ITSP settings) with the order number as Ingram's `customerOrderNumber`, the Ingram part numbers
of the preview, the tenant's address as ship-to and line numbers 1…n (`supplierOrder.lineMap`). The state is
`sending` (with `attemptedAt` and the `sentLines`) before Ingram gets the order; an answer without verdict keeps
it and is answered `502`. A send of an order left `sending` or `failed` first looks it up at Ingram by its number,
before any preview, and takes an order whose lines are the sent ones (never ordering twice) – one with other
lines makes it `failed` and is answered `409`; without a hit it is sent anew. While the last attempt is younger
than two minutes it may still be running and a send is answered `409`; while it is younger than 30 minutes a
search without hit is answered `409` as well (Ingram's search may lag behind; nothing is created again). A clear refusal by Ingram is `failed`
and `502`. A partly taken order (Ingram 207) is `sent` with `supplierOrder.rejectedLines`; a split order keeps
the further Ingram order numbers in `related`. `manual` records an order placed by other means with the
supplier's order number (`externalOrderNumber`, which also fills an empty external number); it may also record
a failed API order the person checked at the distributor. The state is stored at the order (`supplierOrder`);
a sent order turns a draft `open` and publishes `trade.purchaseorder.sent`. An order sent already (also through
EGIS), whose earlier API send is still open or failed (only that channel may continue, a failed one also
`manual`), or neither draft nor open is answered `409`, a supplier ordered through EGIS
`409` with the EGIS route, an order that lacks data `422` with the preview, an order locked by a running
workflow `423` before anything goes out.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `channel` (string): Another available channel than the resolved one; `mail` also with only a `recipient`. (one of `ingram`, `infinigate`, `mail`, `manual`)
- `comment` (string): Remark for the supplier. (max length 500)
- `externalOrderNumber` (string): Manual only: the supplier's order number. (max length 64)
- `recipient` (string (email)): Mail only: overrides the supplier's order mail address. (max length 254)
- `requestedDeliveryDate` (string (date)): Requested delivery date.

Example:

```json
{
  "channel": "mail",
  "comment": "Lieferung bitte an Lager 2",
  "requestedDeliveryDate": "2026-11-03"
}
```

### Responses

- **200** Sent (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** Sent already (also through EGIS), an earlier API send still in flight or not found yet, an order at the distributor that differs, another channel while an API send is open or failed, or neither draft nor open – a plain error (German text); a supplier ordered through EGIS is answered with `code` `use_egis`, `details.channel` `egis` and the EGIS route (`details.route`). (`application/json`)
- **422** The channel is not available for the supplier (`channel_not_available`), or the order lacks data the channel needs (`not_ready`, `details.preview` names it, e.g. the mail recipient). (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the purchase order was created.
- `currency` (string): Currency (ISO 4217).
- `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
- `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
  - `cargoInsurance` (number): Cargo insurance charged.
  - `confirmations` (array of object): Order confirmations of the distributor.
    - `date` (string (date)): Date of the confirmation.
    - `distributorOrderNumber` (string): The distributor's order number.
    - `id` (integer): EGIS id of the confirmation.
    - `lines` (array of object): Confirmed lines.
      - `deliveryDate` (string (date)): Expected delivery date.
      - `position` (integer): Purchase order line.
      - `quantity` (number): Planned delivery quantity.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unitPrice` (number): Confirmed net unit price.
  - `deliveryNotes` (array of object): Delivery notes of the distributor.
    - `date` (string (date)): Date of the delivery note.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `id` (string): EGIS delivery note id.
    - `lines` (array of object): Delivered lines.
      - `description` (string): Description of the article.
      - `ean` (string): EAN (GTIN) of the article.
      - `mpn` (string): Manufacturer part number.
      - `position` (integer): Position number of the line.
      - `quantity` (number): Quantity delivered.
      - `serialNumbers` (array of string): Serial numbers.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unit` (string): Unit of measure.
    - `number` (string): The distributor's delivery note number.
    - `packages` (array of object): Packages of the shipment.
      - `number` (string): Tracking number of the package.
      - `trackingUrl` (string (uri)): Tracking link of the package.
    - `shipper` (string): Carrier of the shipment.
  - `distributorId` (string): EGIS distributor number.
  - `distributorName` (string): Name of the distributor the order went to.
  - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
  - `freightCharge` (number): Freight including additional charges.
  - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
    - `currency` (string): Currency (ISO 4217).
    - `date` (string (date)): Invoice date.
    - `grossAmount` (number): Gross amount of the invoice.
    - `id` (integer): EGIS id of the invoice.
    - `lines` (array of object): Invoiced lines.
      - `description` (string): Description of the article.
      - `netTotal` (number): Net total of the line.
      - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
      - `quantity` (number): Quantity invoiced.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `taxRate` (number): Percent.
      - `unitPrice` (number): Net unit price.
    - `netAmount` (number): Net amount of the invoice.
    - `number` (string): The distributor's invoice number.
    - `vatAmount` (number): VAT amount of the invoice.
  - `link` (string (uri)): The order in the EGIS web application.
  - `orderDate` (string (date)): Order date at EGIS.
  - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
  - `paymentMethod` (string): Payment method of the order at EGIS.
  - `sentAt` (string (date-time)): When the order was sent to EGIS.
  - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
  - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
  - `statusText` (string): Status text of EGIS.
- `goodsReceipts` (array of object): Goods receipts of the purchase order.
  - `grNumber` (string): Number of the goods receipt.
  - `id` (string (uuid)): Id of the goods receipt.
  - `receivedAt` (string (date-time)): When the goods were received.
  - `status` (string): Status of the goods receipt.
- `id` (string (uuid)): Id of the purchase order.
- `lines` (array of POLine): Empty in lists.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid)): Id of the purchase order line.
  - `invoicedQty` (number): Always 0.
  - `mpn` (string): Manufacturer part number.
  - `orderedQty` (number): Quantity ordered.
  - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
  - `position` (integer): Position number of the line.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `receivedQty` (number): Quantity received.
  - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
  - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
- `netTotal` (number): Net total of the purchase order.
- `orderDate` (string (date)): Order date.
- `poNumber` (string): Number of the purchase order.
- `sourceOrders` (array of object): The sales orders the lines were bought for.
  - `id` (string (uuid)): Id of the sales order.
  - `number` (string): Number of the sales order.
- `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
  - `cartId` (string (uuid)): Purchase cart the order was made from.
  - `distributorId` (string): Distributor the cart optimizer chose.
  - `goodsCents` (integer): Goods value of the shipment in cents.
  - `offerKey` (string): Key of the distributor offer.
  - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
  - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
  - `shippingCents` (integer): Shipping cost of the shipment in cents.
  - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
- `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
  - `attemptedAt` (string (date-time)): When the last API send started.
  - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
  - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
  - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
  - `error` (string): Why the last send or refresh failed.
  - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
  - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
  - `invoices` (array of object): Invoices the supplier reported.
    - `date` (string (date)): Invoice date.
    - `grossTotal` (number): Gross total.
    - `netTotal` (number): Net total.
    - `number` (string): Invoice number of the supplier.
  - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
  - `lineMap` (object): Supplier line number → purchase order line id.
  - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
  - `recipient` (string (email)): Where the mail went (mail).
  - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
    - `lineId` (string (uuid)): Id of the purchase order line.
    - `reason` (string): The supplier's reason.
    - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
  - `related` (array of string): Further order numbers when the supplier split the order.
  - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
  - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
  - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
  - `sentAt` (string (date-time)): When the order was sent.
  - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
  - `shipments` (array of object): Shipments the supplier reported.
    - `carrier` (string): Carrier of the shipment.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
    - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
    - `invoiceNumber` (string): The supplier's invoice of the shipment.
    - `lines` (array of object): Lines of the shipment.
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `quantity` (number): Quantity shipped.
      - `serialNumbers` (array of string): Serial numbers.
    - `number` (string): The supplier's delivery note number.
    - `shippedAt` (string (date-time)): When it was shipped.
    - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
    - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
    - `takeoverError` (string): Why the last hand-over failed.
    - `trackingNumber` (string): Tracking number of the carrier.
    - `trackingUrl` (string): Tracking link of the carrier.
  - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
  - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
  - `statusText` (string): The supplier's status text.
- `updatedAt` (string (date-time)): When the purchase order was last changed.

Example 200 answer:

```json
{
  "createdAt": "2026-11-13T09:12:00Z",
  "currency": "EUR",
  "goodsReceipts": [],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
      "invoicedQty": 0,
      "orderedQty": 1,
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "receivedQty": 0,
      "supplierArticleNumber": "KW-RACK12HE",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 289
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
      "invoicedQty": 0,
      "orderedQty": 3,
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "receivedQty": 0,
      "supplierArticleNumber": "KW-CAT7-100",
      "taxRate": 19,
      "unit": "PAK",
      "unitPrice": 64
    }
  ],
  "netTotal": 481,
  "orderDate": "2026-11-13",
  "poNumber": "BE-2026-00068",
  "status": "open",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierOrder": {
    "channel": "mail",
    "comment": "Bitte an den Wareneingang, Tor 2, liefern.",
    "recipient": "bestellung@kabelwerk-sued.example",
    "requestedDeliveryDate": "2026-11-20",
    "revision": 1,
    "sentAt": "2026-11-13T09:20:00Z",
    "state": "sent"
  },
  "updatedAt": "2026-11-13T09:20:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/send' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"channel":"mail","comment":"Lieferung bitte an Lager 2","requestedDeliveryDate":"2026-11-03"}'
```

## Mail a purchase order to its supplier again (tenant:purchase-order:send)

`POST /api/trade/v1/purchase-orders/{id}/send/again`

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

Mails an order sent by mail again with its current content under the next revision (e.g. after a change);
the mail names itself as change ("Änderung <revision> – ersetzt die Bestellung vom <date of the last mail>") in
subject, preheader and text, so the supplier does not take it for a second order;
`recipient` overrides the address; without `comment` / `requestedDeliveryDate` those of the last send are repeated. Two concurrent resends of the same revision send one mail, the other is
answered `409`. Orders sent through another channel are answered `409` (changing an order at a distributor stays
manual).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `channel` (string): Another available channel than the resolved one; `mail` also with only a `recipient`. (one of `ingram`, `infinigate`, `mail`, `manual`)
- `comment` (string): Remark for the supplier. (max length 500)
- `externalOrderNumber` (string): Manual only: the supplier's order number. (max length 64)
- `recipient` (string (email)): Mail only: overrides the supplier's order mail address. (max length 254)
- `requestedDeliveryDate` (string (date)): Requested delivery date.

Example:

```json
{
  "channel": "mail",
  "comment": "Bitte an den Wareneingang, Tor 2, liefern.",
  "requestedDeliveryDate": "2026-11-20"
}
```

### Responses

- **200** Sent again (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** Not sent by mail, not sent yet, sent again meanwhile, or neither draft nor open. (`application/json`)
- **422** The channel is not available for the supplier (`channel_not_available`), or the order lacks data the channel needs (`not_ready`, `details.preview` names it, e.g. the mail recipient). (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the purchase order was created.
- `currency` (string): Currency (ISO 4217).
- `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
- `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
  - `cargoInsurance` (number): Cargo insurance charged.
  - `confirmations` (array of object): Order confirmations of the distributor.
    - `date` (string (date)): Date of the confirmation.
    - `distributorOrderNumber` (string): The distributor's order number.
    - `id` (integer): EGIS id of the confirmation.
    - `lines` (array of object): Confirmed lines.
      - `deliveryDate` (string (date)): Expected delivery date.
      - `position` (integer): Purchase order line.
      - `quantity` (number): Planned delivery quantity.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unitPrice` (number): Confirmed net unit price.
  - `deliveryNotes` (array of object): Delivery notes of the distributor.
    - `date` (string (date)): Date of the delivery note.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `id` (string): EGIS delivery note id.
    - `lines` (array of object): Delivered lines.
      - `description` (string): Description of the article.
      - `ean` (string): EAN (GTIN) of the article.
      - `mpn` (string): Manufacturer part number.
      - `position` (integer): Position number of the line.
      - `quantity` (number): Quantity delivered.
      - `serialNumbers` (array of string): Serial numbers.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unit` (string): Unit of measure.
    - `number` (string): The distributor's delivery note number.
    - `packages` (array of object): Packages of the shipment.
      - `number` (string): Tracking number of the package.
      - `trackingUrl` (string (uri)): Tracking link of the package.
    - `shipper` (string): Carrier of the shipment.
  - `distributorId` (string): EGIS distributor number.
  - `distributorName` (string): Name of the distributor the order went to.
  - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
  - `freightCharge` (number): Freight including additional charges.
  - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
    - `currency` (string): Currency (ISO 4217).
    - `date` (string (date)): Invoice date.
    - `grossAmount` (number): Gross amount of the invoice.
    - `id` (integer): EGIS id of the invoice.
    - `lines` (array of object): Invoiced lines.
      - `description` (string): Description of the article.
      - `netTotal` (number): Net total of the line.
      - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
      - `quantity` (number): Quantity invoiced.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `taxRate` (number): Percent.
      - `unitPrice` (number): Net unit price.
    - `netAmount` (number): Net amount of the invoice.
    - `number` (string): The distributor's invoice number.
    - `vatAmount` (number): VAT amount of the invoice.
  - `link` (string (uri)): The order in the EGIS web application.
  - `orderDate` (string (date)): Order date at EGIS.
  - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
  - `paymentMethod` (string): Payment method of the order at EGIS.
  - `sentAt` (string (date-time)): When the order was sent to EGIS.
  - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
  - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
  - `statusText` (string): Status text of EGIS.
- `goodsReceipts` (array of object): Goods receipts of the purchase order.
  - `grNumber` (string): Number of the goods receipt.
  - `id` (string (uuid)): Id of the goods receipt.
  - `receivedAt` (string (date-time)): When the goods were received.
  - `status` (string): Status of the goods receipt.
- `id` (string (uuid)): Id of the purchase order.
- `lines` (array of POLine): Empty in lists.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid)): Id of the purchase order line.
  - `invoicedQty` (number): Always 0.
  - `mpn` (string): Manufacturer part number.
  - `orderedQty` (number): Quantity ordered.
  - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
  - `position` (integer): Position number of the line.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `receivedQty` (number): Quantity received.
  - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
  - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
- `netTotal` (number): Net total of the purchase order.
- `orderDate` (string (date)): Order date.
- `poNumber` (string): Number of the purchase order.
- `sourceOrders` (array of object): The sales orders the lines were bought for.
  - `id` (string (uuid)): Id of the sales order.
  - `number` (string): Number of the sales order.
- `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
  - `cartId` (string (uuid)): Purchase cart the order was made from.
  - `distributorId` (string): Distributor the cart optimizer chose.
  - `goodsCents` (integer): Goods value of the shipment in cents.
  - `offerKey` (string): Key of the distributor offer.
  - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
  - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
  - `shippingCents` (integer): Shipping cost of the shipment in cents.
  - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
- `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
  - `attemptedAt` (string (date-time)): When the last API send started.
  - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
  - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
  - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
  - `error` (string): Why the last send or refresh failed.
  - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
  - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
  - `invoices` (array of object): Invoices the supplier reported.
    - `date` (string (date)): Invoice date.
    - `grossTotal` (number): Gross total.
    - `netTotal` (number): Net total.
    - `number` (string): Invoice number of the supplier.
  - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
  - `lineMap` (object): Supplier line number → purchase order line id.
  - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
  - `recipient` (string (email)): Where the mail went (mail).
  - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
    - `lineId` (string (uuid)): Id of the purchase order line.
    - `reason` (string): The supplier's reason.
    - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
  - `related` (array of string): Further order numbers when the supplier split the order.
  - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
  - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
  - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
  - `sentAt` (string (date-time)): When the order was sent.
  - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
  - `shipments` (array of object): Shipments the supplier reported.
    - `carrier` (string): Carrier of the shipment.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
    - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
    - `invoiceNumber` (string): The supplier's invoice of the shipment.
    - `lines` (array of object): Lines of the shipment.
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `quantity` (number): Quantity shipped.
      - `serialNumbers` (array of string): Serial numbers.
    - `number` (string): The supplier's delivery note number.
    - `shippedAt` (string (date-time)): When it was shipped.
    - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
    - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
    - `takeoverError` (string): Why the last hand-over failed.
    - `trackingNumber` (string): Tracking number of the carrier.
    - `trackingUrl` (string): Tracking link of the carrier.
  - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
  - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
  - `statusText` (string): The supplier's status text.
- `updatedAt` (string (date-time)): When the purchase order was last changed.

Example 200 answer:

```json
{
  "createdAt": "2026-11-13T09:12:00Z",
  "currency": "EUR",
  "goodsReceipts": [],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
      "invoicedQty": 0,
      "orderedQty": 1,
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "receivedQty": 0,
      "supplierArticleNumber": "KW-RACK12HE",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 289
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
      "invoicedQty": 0,
      "orderedQty": 3,
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "receivedQty": 0,
      "supplierArticleNumber": "KW-CAT7-100",
      "taxRate": 19,
      "unit": "PAK",
      "unitPrice": 64
    }
  ],
  "netTotal": 481,
  "orderDate": "2026-11-13",
  "poNumber": "BE-2026-00068",
  "status": "open",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierOrder": {
    "channel": "mail",
    "comment": "Bitte Liefertermin bestätigen – wir benötigen den Schrank bis 20.11.",
    "recipient": "bestellung@kabelwerk-sued.example",
    "requestedDeliveryDate": "2026-11-20",
    "revision": 2,
    "sentAt": "2026-11-16T14:00:00Z",
    "state": "sent"
  },
  "updatedAt": "2026-11-16T14:00:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/send/again' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"channel":"mail","comment":"Bitte an den Wareneingang, Tor 2, liefern.","requestedDeliveryDate":"2026-11-20"}'
```

## Read the supplier's state of a sent purchase order now (tenant:purchase-order:send)

`POST /api/trade/v1/purchase-orders/{id}/send/refresh`

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

Status, shipments and invoice data from the distributor API the order was sent through (Ingram), instead of
waiting for the next automatic run (every 30 minutes; it also follows orders after ordering was switched off, as
long as the credentials are set). Every new shipment becomes exactly one inbound delivery note
(`shipments[].deliveryNoteId`); new invoice data checks the order's inbound invoices again. A refresh with an
unchanged answer changes nothing. An order left `sending` (the answer of the send got lost) is first searched at
the distributor, search only – it is never sent again: found with the sent lines it becomes `sent` and is followed
right away, not found it stays `sending`.
A refresh while the automatic follow-up runs for the tenant is answered `409`. An order locked by a running workflow cannot
take the supplier's new state and is answered `423`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The order with its supplier state (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** Not sent through a distributor API (mail, manual, EGIS, not sent), or its send failed (`failed`), or the automatic follow-up runs right now. (`application/json`)
- **422** The distributor's credentials are missing in the ITSP settings. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the purchase order was created.
- `currency` (string): Currency (ISO 4217).
- `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
- `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
  - `cargoInsurance` (number): Cargo insurance charged.
  - `confirmations` (array of object): Order confirmations of the distributor.
    - `date` (string (date)): Date of the confirmation.
    - `distributorOrderNumber` (string): The distributor's order number.
    - `id` (integer): EGIS id of the confirmation.
    - `lines` (array of object): Confirmed lines.
      - `deliveryDate` (string (date)): Expected delivery date.
      - `position` (integer): Purchase order line.
      - `quantity` (number): Planned delivery quantity.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unitPrice` (number): Confirmed net unit price.
  - `deliveryNotes` (array of object): Delivery notes of the distributor.
    - `date` (string (date)): Date of the delivery note.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `id` (string): EGIS delivery note id.
    - `lines` (array of object): Delivered lines.
      - `description` (string): Description of the article.
      - `ean` (string): EAN (GTIN) of the article.
      - `mpn` (string): Manufacturer part number.
      - `position` (integer): Position number of the line.
      - `quantity` (number): Quantity delivered.
      - `serialNumbers` (array of string): Serial numbers.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unit` (string): Unit of measure.
    - `number` (string): The distributor's delivery note number.
    - `packages` (array of object): Packages of the shipment.
      - `number` (string): Tracking number of the package.
      - `trackingUrl` (string (uri)): Tracking link of the package.
    - `shipper` (string): Carrier of the shipment.
  - `distributorId` (string): EGIS distributor number.
  - `distributorName` (string): Name of the distributor the order went to.
  - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
  - `freightCharge` (number): Freight including additional charges.
  - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
    - `currency` (string): Currency (ISO 4217).
    - `date` (string (date)): Invoice date.
    - `grossAmount` (number): Gross amount of the invoice.
    - `id` (integer): EGIS id of the invoice.
    - `lines` (array of object): Invoiced lines.
      - `description` (string): Description of the article.
      - `netTotal` (number): Net total of the line.
      - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
      - `quantity` (number): Quantity invoiced.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `taxRate` (number): Percent.
      - `unitPrice` (number): Net unit price.
    - `netAmount` (number): Net amount of the invoice.
    - `number` (string): The distributor's invoice number.
    - `vatAmount` (number): VAT amount of the invoice.
  - `link` (string (uri)): The order in the EGIS web application.
  - `orderDate` (string (date)): Order date at EGIS.
  - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
  - `paymentMethod` (string): Payment method of the order at EGIS.
  - `sentAt` (string (date-time)): When the order was sent to EGIS.
  - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
  - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
  - `statusText` (string): Status text of EGIS.
- `goodsReceipts` (array of object): Goods receipts of the purchase order.
  - `grNumber` (string): Number of the goods receipt.
  - `id` (string (uuid)): Id of the goods receipt.
  - `receivedAt` (string (date-time)): When the goods were received.
  - `status` (string): Status of the goods receipt.
- `id` (string (uuid)): Id of the purchase order.
- `lines` (array of POLine): Empty in lists.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid)): Id of the purchase order line.
  - `invoicedQty` (number): Always 0.
  - `mpn` (string): Manufacturer part number.
  - `orderedQty` (number): Quantity ordered.
  - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
  - `position` (integer): Position number of the line.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `receivedQty` (number): Quantity received.
  - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
  - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
- `netTotal` (number): Net total of the purchase order.
- `orderDate` (string (date)): Order date.
- `poNumber` (string): Number of the purchase order.
- `sourceOrders` (array of object): The sales orders the lines were bought for.
  - `id` (string (uuid)): Id of the sales order.
  - `number` (string): Number of the sales order.
- `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
  - `cartId` (string (uuid)): Purchase cart the order was made from.
  - `distributorId` (string): Distributor the cart optimizer chose.
  - `goodsCents` (integer): Goods value of the shipment in cents.
  - `offerKey` (string): Key of the distributor offer.
  - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
  - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
  - `shippingCents` (integer): Shipping cost of the shipment in cents.
  - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
- `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
  - `attemptedAt` (string (date-time)): When the last API send started.
  - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
  - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
  - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
  - `error` (string): Why the last send or refresh failed.
  - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
  - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
  - `invoices` (array of object): Invoices the supplier reported.
    - `date` (string (date)): Invoice date.
    - `grossTotal` (number): Gross total.
    - `netTotal` (number): Net total.
    - `number` (string): Invoice number of the supplier.
  - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
  - `lineMap` (object): Supplier line number → purchase order line id.
  - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
  - `recipient` (string (email)): Where the mail went (mail).
  - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
    - `lineId` (string (uuid)): Id of the purchase order line.
    - `reason` (string): The supplier's reason.
    - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
  - `related` (array of string): Further order numbers when the supplier split the order.
  - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
  - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
  - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
  - `sentAt` (string (date-time)): When the order was sent.
  - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
  - `shipments` (array of object): Shipments the supplier reported.
    - `carrier` (string): Carrier of the shipment.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
    - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
    - `invoiceNumber` (string): The supplier's invoice of the shipment.
    - `lines` (array of object): Lines of the shipment.
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `quantity` (number): Quantity shipped.
      - `serialNumbers` (array of string): Serial numbers.
    - `number` (string): The supplier's delivery note number.
    - `shippedAt` (string (date-time)): When it was shipped.
    - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
    - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
    - `takeoverError` (string): Why the last hand-over failed.
    - `trackingNumber` (string): Tracking number of the carrier.
    - `trackingUrl` (string): Tracking link of the carrier.
  - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
  - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
  - `statusText` (string): The supplier's status text.
- `updatedAt` (string (date-time)): When the purchase order was last changed.

Example 200 answer:

```json
{
  "createdAt": "2026-11-10T13:00:00Z",
  "currency": "EUR",
  "goodsReceipts": [
    {
      "grNumber": "WE-2026-00050",
      "id": "3d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f21",
      "receivedAt": "2026-11-14T09:30:00Z",
      "status": "posted"
    }
  ],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d73",
  "lines": [
    {
      "articleNumber": "HW-1003",
      "description": "Monitor 27 Zoll QHD, höhenverstellbar",
      "ean": "4061234500038",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e21",
      "invoicedQty": 0,
      "mpn": "27QHD-HV",
      "orderedQty": 4,
      "position": 1,
      "receivedQty": 4,
      "supplierArticleNumber": "7H1234",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 219
    },
    {
      "articleNumber": "HW-1006",
      "description": "Multifunktionsdrucker A4 Farblaser",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e22",
      "invoicedQty": 0,
      "mpn": "MFP-A4C-2026",
      "orderedQty": 1,
      "position": 2,
      "receivedQty": 0,
      "supplierArticleNumber": "7H5678",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 382
    }
  ],
  "netTotal": 1258,
  "orderDate": "2026-11-10",
  "poNumber": "BE-2026-00073",
  "status": "partially_received",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10",
  "supplierOrder": {
    "awaitingDocuments": false,
    "channel": "ingram",
    "expectedDeliveryDate": "2026-11-24",
    "followError": "Ingram meldet die Sendung 8001234567 jetzt mit 5 statt 4 Monitoren; der Lieferschein LE-2026-00010 nennt 4 – bitte prüfen.",
    "lastFollowedAt": "2026-11-18T06:30:00Z",
    "lineMap": {
      "001": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e21",
      "002": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e22"
    },
    "orderNumber": "40-12345",
    "rematchPending": false,
    "revision": 1,
    "sentAt": "2026-11-10T13:05:02Z",
    "shipments": [
      {
        "carrier": "DHL",
        "deliveryNoteId": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a21",
        "handledManually": false,
        "id": "8001234567",
        "invoiceNumber": "6010012345",
        "lines": [
          {
            "lineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e21",
            "quantity": 5
          }
        ],
        "number": "8001234567",
        "shippedAt": "2026-11-12T15:00:00Z",
        "subOrder": "40-12345-11",
        "takeoverAttempts": 0,
        "trackingNumber": "00340434161234567890"
      }
    ],
    "state": "partially_shipped",
    "statusText": "Partially Shipped"
  },
  "updatedAt": "2026-11-18T06:30:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/send/refresh' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Confirm what the supplier follow-up named for a person (tenant:purchase-order:send)

`POST /api/trade/v1/purchase-orders/{id}/send/follow-error/acknowledge`

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

"Abgleich geprüft": a person checked the order's `followError` – e.g. a shipment the distributor reported with more
lines or quantity after it was taken over as delivery note, or a shipment that could not be taken over and was
recorded by hand. The reported shipments are confirmed (`growthChecked`, `handledManually`) and `followError` is
cleared. The follow-up names a shipment again only when a later report grows further; a problem it still finds
(e.g. shipped lines without shipment data) comes back with the next run. An order without `followError` is
answered unchanged. Answered `409` while the automatic follow-up runs for the tenant.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The order with its supplier state (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The automatic follow-up runs right now, or the supplier order changed meanwhile. (`application/json`)
- **422** The supplier follow-up is not set up. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the purchase order was created.
- `currency` (string): Currency (ISO 4217).
- `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
- `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
  - `cargoInsurance` (number): Cargo insurance charged.
  - `confirmations` (array of object): Order confirmations of the distributor.
    - `date` (string (date)): Date of the confirmation.
    - `distributorOrderNumber` (string): The distributor's order number.
    - `id` (integer): EGIS id of the confirmation.
    - `lines` (array of object): Confirmed lines.
      - `deliveryDate` (string (date)): Expected delivery date.
      - `position` (integer): Purchase order line.
      - `quantity` (number): Planned delivery quantity.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unitPrice` (number): Confirmed net unit price.
  - `deliveryNotes` (array of object): Delivery notes of the distributor.
    - `date` (string (date)): Date of the delivery note.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `id` (string): EGIS delivery note id.
    - `lines` (array of object): Delivered lines.
      - `description` (string): Description of the article.
      - `ean` (string): EAN (GTIN) of the article.
      - `mpn` (string): Manufacturer part number.
      - `position` (integer): Position number of the line.
      - `quantity` (number): Quantity delivered.
      - `serialNumbers` (array of string): Serial numbers.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `unit` (string): Unit of measure.
    - `number` (string): The distributor's delivery note number.
    - `packages` (array of object): Packages of the shipment.
      - `number` (string): Tracking number of the package.
      - `trackingUrl` (string (uri)): Tracking link of the package.
    - `shipper` (string): Carrier of the shipment.
  - `distributorId` (string): EGIS distributor number.
  - `distributorName` (string): Name of the distributor the order went to.
  - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
  - `freightCharge` (number): Freight including additional charges.
  - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
    - `currency` (string): Currency (ISO 4217).
    - `date` (string (date)): Invoice date.
    - `grossAmount` (number): Gross amount of the invoice.
    - `id` (integer): EGIS id of the invoice.
    - `lines` (array of object): Invoiced lines.
      - `description` (string): Description of the article.
      - `netTotal` (number): Net total of the line.
      - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
      - `quantity` (number): Quantity invoiced.
      - `supplierArticleNumber` (string): The distributor's article number.
      - `taxRate` (number): Percent.
      - `unitPrice` (number): Net unit price.
    - `netAmount` (number): Net amount of the invoice.
    - `number` (string): The distributor's invoice number.
    - `vatAmount` (number): VAT amount of the invoice.
  - `link` (string (uri)): The order in the EGIS web application.
  - `orderDate` (string (date)): Order date at EGIS.
  - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
  - `paymentMethod` (string): Payment method of the order at EGIS.
  - `sentAt` (string (date-time)): When the order was sent to EGIS.
  - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
  - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
  - `statusText` (string): Status text of EGIS.
- `goodsReceipts` (array of object): Goods receipts of the purchase order.
  - `grNumber` (string): Number of the goods receipt.
  - `id` (string (uuid)): Id of the goods receipt.
  - `receivedAt` (string (date-time)): When the goods were received.
  - `status` (string): Status of the goods receipt.
- `id` (string (uuid)): Id of the purchase order.
- `lines` (array of POLine): Empty in lists.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `id` (string (uuid)): Id of the purchase order line.
  - `invoicedQty` (number): Always 0.
  - `mpn` (string): Manufacturer part number.
  - `orderedQty` (number): Quantity ordered.
  - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
  - `position` (integer): Position number of the line.
  - `productId` (string (uuid)): Masterdata article (product) id.
  - `receivedQty` (number): Quantity received.
  - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
  - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
  - `taxRate` (number): Tax rate in percent.
  - `unit` (string): Unit of measure.
  - `unitPrice` (number): Net unit price.
- `netTotal` (number): Net total of the purchase order.
- `orderDate` (string (date)): Order date.
- `poNumber` (string): Number of the purchase order.
- `sourceOrders` (array of object): The sales orders the lines were bought for.
  - `id` (string (uuid)): Id of the sales order.
  - `number` (string): Number of the sales order.
- `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
  - `cartId` (string (uuid)): Purchase cart the order was made from.
  - `distributorId` (string): Distributor the cart optimizer chose.
  - `goodsCents` (integer): Goods value of the shipment in cents.
  - `offerKey` (string): Key of the distributor offer.
  - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
  - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
  - `shippingCents` (integer): Shipping cost of the shipment in cents.
  - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
- `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
  - `attemptedAt` (string (date-time)): When the last API send started.
  - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
  - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
  - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
  - `error` (string): Why the last send or refresh failed.
  - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
  - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
  - `invoices` (array of object): Invoices the supplier reported.
    - `date` (string (date)): Invoice date.
    - `grossTotal` (number): Gross total.
    - `netTotal` (number): Net total.
    - `number` (string): Invoice number of the supplier.
  - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
  - `lineMap` (object): Supplier line number → purchase order line id.
  - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
  - `recipient` (string (email)): Where the mail went (mail).
  - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
    - `lineId` (string (uuid)): Id of the purchase order line.
    - `reason` (string): The supplier's reason.
    - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
  - `related` (array of string): Further order numbers when the supplier split the order.
  - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
  - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
  - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
  - `sentAt` (string (date-time)): When the order was sent.
  - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
  - `shipments` (array of object): Shipments the supplier reported.
    - `carrier` (string): Carrier of the shipment.
    - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
    - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
    - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
    - `invoiceNumber` (string): The supplier's invoice of the shipment.
    - `lines` (array of object): Lines of the shipment.
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `quantity` (number): Quantity shipped.
      - `serialNumbers` (array of string): Serial numbers.
    - `number` (string): The supplier's delivery note number.
    - `shippedAt` (string (date-time)): When it was shipped.
    - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
    - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
    - `takeoverError` (string): Why the last hand-over failed.
    - `trackingNumber` (string): Tracking number of the carrier.
    - `trackingUrl` (string): Tracking link of the carrier.
  - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
  - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
  - `statusText` (string): The supplier's status text.
- `updatedAt` (string (date-time)): When the purchase order was last changed.

Example 200 answer:

```json
{
  "createdAt": "2026-11-10T13:00:00Z",
  "currency": "EUR",
  "goodsReceipts": [
    {
      "grNumber": "WE-2026-00050",
      "id": "3d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f21",
      "receivedAt": "2026-11-14T09:30:00Z",
      "status": "posted"
    }
  ],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d73",
  "lines": [
    {
      "articleNumber": "HW-1003",
      "description": "Monitor 27 Zoll QHD, höhenverstellbar",
      "ean": "4061234500038",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e21",
      "invoicedQty": 0,
      "mpn": "27QHD-HV",
      "orderedQty": 4,
      "position": 1,
      "receivedQty": 4,
      "supplierArticleNumber": "7H1234",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 219
    },
    {
      "articleNumber": "HW-1006",
      "description": "Multifunktionsdrucker A4 Farblaser",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e22",
      "invoicedQty": 0,
      "mpn": "MFP-A4C-2026",
      "orderedQty": 1,
      "position": 2,
      "receivedQty": 0,
      "supplierArticleNumber": "7H5678",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 382
    }
  ],
  "netTotal": 1258,
  "orderDate": "2026-11-10",
  "poNumber": "BE-2026-00073",
  "status": "partially_received",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10",
  "supplierOrder": {
    "attemptedAt": "2026-11-10T13:05:00Z",
    "awaitingDocuments": false,
    "channel": "ingram",
    "expectedDeliveryDate": "2026-11-24",
    "invoices": [
      {
        "date": "2026-11-12",
        "grossTotal": 1042.44,
        "netTotal": 876,
        "number": "6010012345"
      }
    ],
    "lastFollowedAt": "2026-11-18T06:30:00Z",
    "lineMap": {
      "001": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e21",
      "002": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e22"
    },
    "orderNumber": "40-12345",
    "rematchPending": false,
    "revision": 1,
    "sentAt": "2026-11-10T13:05:02Z",
    "sentLines": {
      "001": {
        "quantity": 4,
        "supplierArticleNumber": "7H1234"
      },
      "002": {
        "quantity": 1,
        "supplierArticleNumber": "7H5678"
      }
    },
    "shipments": [
      {
        "carrier": "DHL",
        "deliveryNoteId": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a21",
        "handledManually": false,
        "id": "8001234567",
        "invoiceNumber": "6010012345",
        "lines": [
          {
            "lineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e21",
            "quantity": 4,
            "serialNumbers": [
              "MON27-8812",
              "MON27-8813",
              "MON27-8814",
              "MON27-8815"
            ]
          }
        ],
        "number": "8001234567",
        "shippedAt": "2026-11-12T15:00:00Z",
        "subOrder": "40-12345-11",
        "takeoverAttempts": 0,
        "trackingNumber": "00340434161234567890",
        "trackingUrl": "https://tracking.example/00340434161234567890"
      }
    ],
    "state": "partially_shipped",
    "statusText": "Partially Shipped"
  },
  "updatedAt": "2026-11-18T06:30:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/send/follow-error/acknowledge' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List goods receipts (tenant:trade:purchasing:read)

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

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

Pages by keyset in creation order (newest first, then id; `nextCursor`), a page shown newest receipt first, without lines; `total` counts all matches.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `poId` | query | string (uuid) |  | Only receipts of this purchase order. |
| `limit` | query | integer |  | Page size; at most 500. (default `50`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** Goods receipts (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of GoodsReceipt, required): The goods receipts of the page.
  - `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`)
- `total` (integer, required): Number of entries of the whole list.
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-18T10:15:00Z",
      "grNumber": "WE-2026-00052",
      "id": "3d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f52",
      "lines": [],
      "poId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
      "poNumber": "BE-2026-00068",
      "receivedAt": "2026-11-18T10:15:00Z",
      "status": "posted"
    },
    {
      "createdAt": "2026-11-14T09:30:00Z",
      "grNumber": "WE-2026-00050",
      "id": "3d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f21",
      "lines": [],
      "poId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d73",
      "poNumber": "BE-2026-00073",
      "receivedAt": "2026-11-14T09:30:00Z",
      "status": "posted"
    }
  ],
  "nextCursor": "Y3JlYXRlZHwyMDI2LTExLTE0VDA5OjMwOjAwWnwzZDZlN2Y4YS05YjBjLTRkMWUtOGYyYS00YjVjNmQ3ZThmMjE",
  "total": 11
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/goods-receipts' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## 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"}'
```

## Get a goods receipt (tenant:trade:purchasing:read)

`GET /api/trade/v1/goods-receipts/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Goods receipt (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 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 200 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 GET 'https://api.mbcom.cloud/api/trade/v1/goods-receipts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Purchasing

## List purchase recommendations (tenant:trade:purchasing:read)

`GET /api/trade/v1/purchase-recommendations`

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

Purchase recommendations (Bestellvorschläge), oldest first: the uncovered rest of an open sales order line
(`source` `order`; drop-ship lines carry the customer's `shipTo`) and refills of articles below their minimum
stock (`source` `stock`). They are recomputed in the background whenever orders, purchase orders, goods receipts
or stock change, and with `recomputePurchaseRecommendations`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string |  | (one of `open`, `in_cart`, `ordered`, `dismissed`) |
| `source` | query | string |  | (one of `order`, `stock`) |
| `orderId` | query | string (uuid) |  | Only the recommendations of this sales order. |

### Responses

- **200** Recommendations (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of PurchaseRecommendation)
  - `articleId` (string): Masterdata product id (empty for an order line without article).
  - `cartId` (string (uuid)): The cart of an `in_cart` recommendation.
  - `dismissReason` (string): Why it was dismissed; set while dismissed.
  - `dropShip` (boolean): The supplier delivers straight to the customer (`shipTo`).
  - `id` (string (uuid)): Id of the recommendation.
  - `key` (string): Stable key: the first revision of the order line, or the article and warehouse of a stock refill.
  - `orderId` (string (uuid)): Sales order the recommendation is for; absent for minimum stock.
  - `orderLineId` (string (uuid)): The current revision of the sales order line.
  - `orderNumber` (string): Number of that sales order.
  - `pendingNeed` (number): Set while `in_cart` when the need changed since: the current need (0 = no need any more).
  - `quantity` (number): The need; while `in_cart` the quantity in the cart.
  - `reason` (string): Why (German), e.g. `Auftrag AB-2026-00012 Pos. 3 nicht gedeckt`.
  - `removedNeed` (number): Set on an open recommendation a person took out of a cart: the automatic cart leaves it alone up to this quantity.
  - `shipTo` (object): Delivery address of a drop-ship recommendation.
  - `source` (string): `order`: the uncovered rest of a sales order line; `stock`: refill below the minimum stock. (one of `order`, `stock`)
  - `status` (string): `open`, `in_cart`, `ordered` or `dismissed`. (one of `open`, `in_cart`, `ordered`, `dismissed`)
  - `updatedAt` (string (date-time)): When the recommendation was last changed.
  - `warehouseId` (string): Warehouse of a stock line (empty for drop shipment).
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "dropShip": false,
      "id": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
      "key": "stock:4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07:HAUPT",
      "quantity": 16,
      "reason": "Mindestbestand 10 unterschritten (frei 4)",
      "source": "stock",
      "status": "open",
      "updatedAt": "2026-11-19T06:15:00Z",
      "warehouseId": "HAUPT"
    },
    {
      "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "cartId": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
      "dropShip": false,
      "id": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02",
      "key": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "orderId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "orderLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "orderNumber": "AB-2026-0143",
      "quantity": 6,
      "reason": "Auftrag AB-2026-0143 Pos. 1 nicht gedeckt",
      "source": "order",
      "status": "in_cart",
      "updatedAt": "2026-11-06T10:20:00Z"
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/purchase-recommendations' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Recompute the purchase recommendations now (tenant:purchase-recommendation:write)

`POST /api/trade/v1/purchase-recommendations/recompute`

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

Recomputes the tenant's recommendations at once instead of waiting for the background run: open ones get the
current need (or close when it is gone), dismissed ones open again when their need changed; recommendations in a
cart or ordered are never changed. With `procurement.autoCart` the open recommendations then go into the
automatic cart. Publishes `trade.purchase_recommendations.changed` when something changed.
This is a heavy operation (it reads every open order, purchase order and stock level of the tenant) and runs
synchronously; call it after bulk changes, not per change – the background run catches up within a minute.
When only filling the automatic cart failed, the recompute stands: `200` with `warning`.

### Responses

- **200** What changed (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **500** The recompute failed. (`application/json`)

Fields of the 200 answer:

- `closed` (integer): Number of recommendations closed.
- `opened` (integer): New or reopened recommendations.
- `openedIds` (array of string (uuid)): Ids of the recommendations opened.
- `updated` (integer): Number of recommendations updated.
- `warning` (string): Set (German) when the recompute stands but the automatic cart could not be filled; it is filled on the next run.

Example 200 answer:

```json
{
  "closed": 0,
  "opened": 1,
  "openedIds": [
    "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01"
  ],
  "updated": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-recommendations/recompute' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Dismiss a purchase recommendation (tenant:purchase-recommendation:write)

`POST /api/trade/v1/purchase-recommendations/{id}/dismiss`

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

Sets an open recommendation aside with a reason (required, `422` without). It stays dismissed while its need stays the same; a different need opens it again.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `reason` (string, required)

Example:

```json
{
  "reason": "Kunde holt selbst ab"
}
```

### Responses

- **200** Dismissed (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** Not open (`recommendation_not_open`). (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 200 answer:

- `articleId` (string): Masterdata product id (empty for an order line without article).
- `cartId` (string (uuid)): The cart of an `in_cart` recommendation.
- `dismissReason` (string): Why it was dismissed; set while dismissed.
- `dropShip` (boolean): The supplier delivers straight to the customer (`shipTo`).
- `id` (string (uuid)): Id of the recommendation.
- `key` (string): Stable key: the first revision of the order line, or the article and warehouse of a stock refill.
- `orderId` (string (uuid)): Sales order the recommendation is for; absent for minimum stock.
- `orderLineId` (string (uuid)): The current revision of the sales order line.
- `orderNumber` (string): Number of that sales order.
- `pendingNeed` (number): Set while `in_cart` when the need changed since: the current need (0 = no need any more).
- `quantity` (number): The need; while `in_cart` the quantity in the cart.
- `reason` (string): Why (German), e.g. `Auftrag AB-2026-00012 Pos. 3 nicht gedeckt`.
- `removedNeed` (number): Set on an open recommendation a person took out of a cart: the automatic cart leaves it alone up to this quantity.
- `shipTo` (object): Delivery address of a drop-ship recommendation.
- `source` (string): `order`: the uncovered rest of a sales order line; `stock`: refill below the minimum stock. (one of `order`, `stock`)
- `status` (string): `open`, `in_cart`, `ordered` or `dismissed`. (one of `open`, `in_cart`, `ordered`, `dismissed`)
- `updatedAt` (string (date-time)): When the recommendation was last changed.
- `warehouseId` (string): Warehouse of a stock line (empty for drop shipment).

Example 200 answer:

```json
{
  "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
  "dismissReason": "Kunde holt selbst ab",
  "dropShip": false,
  "id": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
  "key": "stock:4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07:HAUPT",
  "quantity": 16,
  "reason": "Mindestbestand 10 unterschritten (frei 4)",
  "source": "stock",
  "status": "dismissed",
  "updatedAt": "2026-11-19T07:00:00Z",
  "warehouseId": "HAUPT"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-recommendations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/dismiss' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"Kunde holt selbst ab"}'
```

## Restore a dismissed purchase recommendation (tenant:purchase-recommendation:write)

`POST /api/trade/v1/purchase-recommendations/{id}/restore`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Open again (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** Not dismissed (`invalid_state`). (`application/json`)

Fields of the 200 answer:

- `articleId` (string): Masterdata product id (empty for an order line without article).
- `cartId` (string (uuid)): The cart of an `in_cart` recommendation.
- `dismissReason` (string): Why it was dismissed; set while dismissed.
- `dropShip` (boolean): The supplier delivers straight to the customer (`shipTo`).
- `id` (string (uuid)): Id of the recommendation.
- `key` (string): Stable key: the first revision of the order line, or the article and warehouse of a stock refill.
- `orderId` (string (uuid)): Sales order the recommendation is for; absent for minimum stock.
- `orderLineId` (string (uuid)): The current revision of the sales order line.
- `orderNumber` (string): Number of that sales order.
- `pendingNeed` (number): Set while `in_cart` when the need changed since: the current need (0 = no need any more).
- `quantity` (number): The need; while `in_cart` the quantity in the cart.
- `reason` (string): Why (German), e.g. `Auftrag AB-2026-00012 Pos. 3 nicht gedeckt`.
- `removedNeed` (number): Set on an open recommendation a person took out of a cart: the automatic cart leaves it alone up to this quantity.
- `shipTo` (object): Delivery address of a drop-ship recommendation.
- `source` (string): `order`: the uncovered rest of a sales order line; `stock`: refill below the minimum stock. (one of `order`, `stock`)
- `status` (string): `open`, `in_cart`, `ordered` or `dismissed`. (one of `open`, `in_cart`, `ordered`, `dismissed`)
- `updatedAt` (string (date-time)): When the recommendation was last changed.
- `warehouseId` (string): Warehouse of a stock line (empty for drop shipment).

Example 200 answer:

```json
{
  "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
  "dropShip": false,
  "id": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
  "key": "stock:4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07:HAUPT",
  "quantity": 16,
  "reason": "Mindestbestand 10 unterschritten (frei 4)",
  "source": "stock",
  "status": "open",
  "updatedAt": "2026-11-19T06:15:00Z",
  "warehouseId": "HAUPT"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-recommendations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/restore' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List purchase carts (tenant:trade:purchasing:read)

`GET /api/trade/v1/purchase-carts`

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

The tenant's carts with their lines, newest first.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string |  | (one of `open`, `ordered`, `discarded`) |

### Responses

- **200** Carts (`application/json`)
- **401** No valid session or bearer token (no body).
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 200 answer:

- `items` (array of PurchaseCart)
  - `createdAt` (string (date-time)): When the cart was created.
  - `createdBy` (string): Who created the cart.
  - `id` (string (uuid)): Id of the cart.
  - `kind` (string): `auto`: the tenant's single automatic cart (`procurement.autoCart`), "Automatische Vorschläge". (one of `manual`, `auto`)
  - `lines` (array of PurchaseCartLine): Lines of the cart.
    - `articleNumber` (string): Article number in masterdata.
    - `description` (string): Description of the article.
    - `ean` (string): EAN (GTIN) of the article.
    - `flag` (string): Set when the sales order changed after the line went into the cart, e.g. `Kein Bedarf mehr`.
    - `id` (string (uuid)): Id of the cart line.
    - `manufacturer` (string): Manufacturer of the article.
    - `mpn` (string): Manufacturer part number.
    - `pinnedOffer` (string): Offer key the optimizer must use.
    - `poId` (string (uuid)): The purchase order the line is on.
    - `poLineId` (string (uuid)): Purchase order line the line became once accepted.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `recommendationId` (string (uuid)): Purchase recommendation the line came from.
    - `shipTo` (object): Customer address of a drop-ship line.
    - `shipToKind` (string): `stock` or `drop_ship`. (one of `stock`, `drop_ship`)
    - `sourceIdentifiers` (object): Article id per connector, e.g. `egis`: PCS number.
    - `sourceLineId` (string (uuid)): The sales order line (current revision).
    - `unit` (string): Unit of measure.
  - `name` (string): Name of the cart.
  - `proposal` (PurchaseCartProposal): The optimizer's split of the cart; amounts are net EUR cents.
    - `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
    - `acceptedAt` (string (date-time)): Set when every group is accepted.
    - `cartVersion` (integer): Version of the cart the proposal was computed for.
    - `id` (string): Id of the proposal.
    - `maxDays` (integer): Longest delivery time of the proposal in days.
    - `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
    - `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
    - `offers` (object): The offers used, per article key.
    - `optimizedAt` (string (date-time)): When the proposal was computed.
    - `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
    - `shipments` (array of object): One future purchase order each (offer key and ship-to).
      - `assignments` (array of object): Cart lines the shipment carries.
        - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
        - `lineId` (string (uuid)): Id of the cart line.
        - `offerKey` (string): Key of the distributor offer.
        - `priceCents` (integer): Unit price in cents.
        - `quantity` (number): Quantity assigned.
      - `days` (integer): Delivery days.
      - `dropShip` (boolean): The shipment goes straight to the customer.
      - `dropShipFeeCents` (integer): Drop-ship fee in cents.
      - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
      - `goodsCents` (integer): Goods value in cents.
      - `offerKey` (string): Key of the distributor offer the shipment uses.
      - `shipToKey` (string): `stock` or the drop-ship address key.
      - `shippingCents` (integer): Shipping cost in cents.
      - `supplierAddressId` (string): Masterdata address of the supplier.
      - `surchargeCents` (integer): Minimum-order surcharge in cents.
      - `totalCents` (integer): Total of the shipment in cents.
    - `totalCents` (integer): Total of the proposal in cents.
    - `unassigned` (array of object): Lines (or rests) no usable offer covers.
      - `lineId` (string (uuid)): Id of the cart line.
      - `missingQty` (number): Quantity no offer covers.
      - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
    - `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
      - `connector` (string): Connector that did not answer fully.
      - `message` (string): What went wrong.
  - `status` (string): Status of the cart (`open`, `ordered`, `discarded`). (one of `open`, `ordered`, `discarded`)
  - `updatedAt` (string (date-time)): When the cart was last changed.
  - `version` (integer): Raised by every change; a proposal is valid for one version.
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-17T08:00:00Z",
      "createdBy": "anna.weber@muster-it.example",
      "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
      "kind": "manual",
      "name": "Wochenbestellung KW 47",
      "status": "open",
      "updatedAt": "2026-11-19T07:35:00Z",
      "version": 4
    },
    {
      "createdAt": "2026-09-01T06:00:00Z",
      "createdBy": "system",
      "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d02",
      "kind": "auto",
      "name": "Automatische Vorschläge",
      "status": "open",
      "updatedAt": "2026-11-19T06:15:00Z",
      "version": 11
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/purchase-carts' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a purchase cart (tenant:purchase-cart:write)

`POST /api/trade/v1/purchase-carts`

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

A cart spans every distributor; several carts can be open at once.

### Request body

`application/json` (required)

- `name` (string, required)

Example:

```json
{
  "name": "Wochenbestellung"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 201 answer:

- `createdAt` (string (date-time)): When the cart was created.
- `createdBy` (string): Who created the cart.
- `id` (string (uuid)): Id of the cart.
- `kind` (string): `auto`: the tenant's single automatic cart (`procurement.autoCart`), "Automatische Vorschläge". (one of `manual`, `auto`)
- `lines` (array of PurchaseCartLine): Lines of the cart.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the article.
  - `ean` (string): EAN (GTIN) of the article.
  - `flag` (string): Set when the sales order changed after the line went into the cart, e.g. `Kein Bedarf mehr`.
  - `id` (string (uuid)): Id of the cart line.
  - `manufacturer` (string): Manufacturer of the article.
  - `mpn` (string): Manufacturer part number.
  - `pinnedOffer` (string): Offer key the optimizer must use.
  - `poId` (string (uuid)): The purchase order the line is on.
  - `poLineId` (string (uuid)): Purchase order line the line became once accepted.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `recommendationId` (string (uuid)): Purchase recommendation the line came from.
  - `shipTo` (object): Customer address of a drop-ship line.
  - `shipToKind` (string): `stock` or `drop_ship`. (one of `stock`, `drop_ship`)
  - `sourceIdentifiers` (object): Article id per connector, e.g. `egis`: PCS number.
  - `sourceLineId` (string (uuid)): The sales order line (current revision).
  - `unit` (string): Unit of measure.
- `name` (string): Name of the cart.
- `proposal` (PurchaseCartProposal): The optimizer's split of the cart; amounts are net EUR cents.
  - `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
  - `acceptedAt` (string (date-time)): Set when every group is accepted.
  - `cartVersion` (integer): Version of the cart the proposal was computed for.
  - `id` (string): Id of the proposal.
  - `maxDays` (integer): Longest delivery time of the proposal in days.
  - `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
  - `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
  - `offers` (object): The offers used, per article key.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
  - `shipments` (array of object): One future purchase order each (offer key and ship-to).
    - `assignments` (array of object): Cart lines the shipment carries.
      - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
      - `lineId` (string (uuid)): Id of the cart line.
      - `offerKey` (string): Key of the distributor offer.
      - `priceCents` (integer): Unit price in cents.
      - `quantity` (number): Quantity assigned.
    - `days` (integer): Delivery days.
    - `dropShip` (boolean): The shipment goes straight to the customer.
    - `dropShipFeeCents` (integer): Drop-ship fee in cents.
    - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
    - `goodsCents` (integer): Goods value in cents.
    - `offerKey` (string): Key of the distributor offer the shipment uses.
    - `shipToKey` (string): `stock` or the drop-ship address key.
    - `shippingCents` (integer): Shipping cost in cents.
    - `supplierAddressId` (string): Masterdata address of the supplier.
    - `surchargeCents` (integer): Minimum-order surcharge in cents.
    - `totalCents` (integer): Total of the shipment in cents.
  - `totalCents` (integer): Total of the proposal in cents.
  - `unassigned` (array of object): Lines (or rests) no usable offer covers.
    - `lineId` (string (uuid)): Id of the cart line.
    - `missingQty` (number): Quantity no offer covers.
    - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
  - `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
    - `connector` (string): Connector that did not answer fully.
    - `message` (string): What went wrong.
- `status` (string): Status of the cart (`open`, `ordered`, `discarded`). (one of `open`, `ordered`, `discarded`)
- `updatedAt` (string (date-time)): When the cart was last changed.
- `version` (integer): Raised by every change; a proposal is valid for one version.

Example 201 answer:

```json
{
  "createdAt": "2026-11-19T08:00:00Z",
  "createdBy": "anna.weber@muster-it.example",
  "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d03",
  "kind": "manual",
  "lines": [],
  "name": "Wochenbestellung",
  "status": "open",
  "updatedAt": "2026-11-19T08:00:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-carts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Wochenbestellung"}'
```

## Get a purchase cart with its lines and proposal (tenant:trade:purchasing:read)

`GET /api/trade/v1/purchase-carts/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Cart (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the cart was created.
- `createdBy` (string): Who created the cart.
- `id` (string (uuid)): Id of the cart.
- `kind` (string): `auto`: the tenant's single automatic cart (`procurement.autoCart`), "Automatische Vorschläge". (one of `manual`, `auto`)
- `lines` (array of PurchaseCartLine): Lines of the cart.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the article.
  - `ean` (string): EAN (GTIN) of the article.
  - `flag` (string): Set when the sales order changed after the line went into the cart, e.g. `Kein Bedarf mehr`.
  - `id` (string (uuid)): Id of the cart line.
  - `manufacturer` (string): Manufacturer of the article.
  - `mpn` (string): Manufacturer part number.
  - `pinnedOffer` (string): Offer key the optimizer must use.
  - `poId` (string (uuid)): The purchase order the line is on.
  - `poLineId` (string (uuid)): Purchase order line the line became once accepted.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `recommendationId` (string (uuid)): Purchase recommendation the line came from.
  - `shipTo` (object): Customer address of a drop-ship line.
  - `shipToKind` (string): `stock` or `drop_ship`. (one of `stock`, `drop_ship`)
  - `sourceIdentifiers` (object): Article id per connector, e.g. `egis`: PCS number.
  - `sourceLineId` (string (uuid)): The sales order line (current revision).
  - `unit` (string): Unit of measure.
- `name` (string): Name of the cart.
- `proposal` (PurchaseCartProposal): The optimizer's split of the cart; amounts are net EUR cents.
  - `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
  - `acceptedAt` (string (date-time)): Set when every group is accepted.
  - `cartVersion` (integer): Version of the cart the proposal was computed for.
  - `id` (string): Id of the proposal.
  - `maxDays` (integer): Longest delivery time of the proposal in days.
  - `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
  - `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
  - `offers` (object): The offers used, per article key.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
  - `shipments` (array of object): One future purchase order each (offer key and ship-to).
    - `assignments` (array of object): Cart lines the shipment carries.
      - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
      - `lineId` (string (uuid)): Id of the cart line.
      - `offerKey` (string): Key of the distributor offer.
      - `priceCents` (integer): Unit price in cents.
      - `quantity` (number): Quantity assigned.
    - `days` (integer): Delivery days.
    - `dropShip` (boolean): The shipment goes straight to the customer.
    - `dropShipFeeCents` (integer): Drop-ship fee in cents.
    - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
    - `goodsCents` (integer): Goods value in cents.
    - `offerKey` (string): Key of the distributor offer the shipment uses.
    - `shipToKey` (string): `stock` or the drop-ship address key.
    - `shippingCents` (integer): Shipping cost in cents.
    - `supplierAddressId` (string): Masterdata address of the supplier.
    - `surchargeCents` (integer): Minimum-order surcharge in cents.
    - `totalCents` (integer): Total of the shipment in cents.
  - `totalCents` (integer): Total of the proposal in cents.
  - `unassigned` (array of object): Lines (or rests) no usable offer covers.
    - `lineId` (string (uuid)): Id of the cart line.
    - `missingQty` (number): Quantity no offer covers.
    - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
  - `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
    - `connector` (string): Connector that did not answer fully.
    - `message` (string): What went wrong.
- `status` (string): Status of the cart (`open`, `ordered`, `discarded`). (one of `open`, `ordered`, `discarded`)
- `updatedAt` (string (date-time)): When the cart was last changed.
- `version` (integer): Raised by every change; a proposal is valid for one version.

Example 200 answer:

```json
{
  "createdAt": "2026-11-17T08:00:00Z",
  "createdBy": "anna.weber@muster-it.example",
  "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
  "kind": "manual",
  "lines": [
    {
      "articleNumber": "NW-2002",
      "description": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
      "manufacturer": "Kabelwerk",
      "mpn": "AP-WIFI6-C",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "masterdata": "KW-AP-WIFI6"
      },
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "unit": "STK"
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
      "manufacturer": "Nordlicht",
      "mpn": "HS-USB-ANC",
      "pinnedOffer": "egis:70044",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "quantity": 16,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "egis": "PCS400942",
        "masterdata": "NL-HS-USB-ANC"
      },
      "unit": "STK"
    }
  ],
  "name": "Wochenbestellung KW 47",
  "status": "open",
  "updatedAt": "2026-11-19T07:35:00Z",
  "version": 4
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Discard a purchase cart (tenant:purchase-cart:write)

`DELETE /api/trade/v1/purchase-carts/{id}`

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

The cart becomes `discarded`; its recommendations are open again and its lines stay as history.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Discarded
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The cart does not allow it (`code`): `cart_not_open` (ordered or discarded), `recommendation_not_open`,
`line_ordered` (the line is on a purchase order), `nothing_to_order`, `no_proposal` (optimize first),
`proposal_stale` / `cart_changed` (optimize again), `accept_in_progress` (an optimization, accept or order of
the cart is running; retry shortly), `drop_ship_no_address` (a drop-ship order has no delivery address).
 (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Rename a purchase cart (tenant:purchase-cart:write)

`PATCH /api/trade/v1/purchase-carts/{id}`

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

Only open carts. The proposal stays valid.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `name` (string, required)

Example:

```json
{
  "name": "Wochenbestellung KW 47"
}
```

### Responses

- **200** Renamed (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The cart does not allow it (`code`): `cart_not_open` (ordered or discarded), `recommendation_not_open`,
`line_ordered` (the line is on a purchase order), `nothing_to_order`, `no_proposal` (optimize first),
`proposal_stale` / `cart_changed` (optimize again), `accept_in_progress` (an optimization, accept or order of
the cart is running; retry shortly), `drop_ship_no_address` (a drop-ship order has no delivery address).
 (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the cart was created.
- `createdBy` (string): Who created the cart.
- `id` (string (uuid)): Id of the cart.
- `kind` (string): `auto`: the tenant's single automatic cart (`procurement.autoCart`), "Automatische Vorschläge". (one of `manual`, `auto`)
- `lines` (array of PurchaseCartLine): Lines of the cart.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the article.
  - `ean` (string): EAN (GTIN) of the article.
  - `flag` (string): Set when the sales order changed after the line went into the cart, e.g. `Kein Bedarf mehr`.
  - `id` (string (uuid)): Id of the cart line.
  - `manufacturer` (string): Manufacturer of the article.
  - `mpn` (string): Manufacturer part number.
  - `pinnedOffer` (string): Offer key the optimizer must use.
  - `poId` (string (uuid)): The purchase order the line is on.
  - `poLineId` (string (uuid)): Purchase order line the line became once accepted.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `recommendationId` (string (uuid)): Purchase recommendation the line came from.
  - `shipTo` (object): Customer address of a drop-ship line.
  - `shipToKind` (string): `stock` or `drop_ship`. (one of `stock`, `drop_ship`)
  - `sourceIdentifiers` (object): Article id per connector, e.g. `egis`: PCS number.
  - `sourceLineId` (string (uuid)): The sales order line (current revision).
  - `unit` (string): Unit of measure.
- `name` (string): Name of the cart.
- `proposal` (PurchaseCartProposal): The optimizer's split of the cart; amounts are net EUR cents.
  - `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
  - `acceptedAt` (string (date-time)): Set when every group is accepted.
  - `cartVersion` (integer): Version of the cart the proposal was computed for.
  - `id` (string): Id of the proposal.
  - `maxDays` (integer): Longest delivery time of the proposal in days.
  - `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
  - `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
  - `offers` (object): The offers used, per article key.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
  - `shipments` (array of object): One future purchase order each (offer key and ship-to).
    - `assignments` (array of object): Cart lines the shipment carries.
      - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
      - `lineId` (string (uuid)): Id of the cart line.
      - `offerKey` (string): Key of the distributor offer.
      - `priceCents` (integer): Unit price in cents.
      - `quantity` (number): Quantity assigned.
    - `days` (integer): Delivery days.
    - `dropShip` (boolean): The shipment goes straight to the customer.
    - `dropShipFeeCents` (integer): Drop-ship fee in cents.
    - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
    - `goodsCents` (integer): Goods value in cents.
    - `offerKey` (string): Key of the distributor offer the shipment uses.
    - `shipToKey` (string): `stock` or the drop-ship address key.
    - `shippingCents` (integer): Shipping cost in cents.
    - `supplierAddressId` (string): Masterdata address of the supplier.
    - `surchargeCents` (integer): Minimum-order surcharge in cents.
    - `totalCents` (integer): Total of the shipment in cents.
  - `totalCents` (integer): Total of the proposal in cents.
  - `unassigned` (array of object): Lines (or rests) no usable offer covers.
    - `lineId` (string (uuid)): Id of the cart line.
    - `missingQty` (number): Quantity no offer covers.
    - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
  - `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
    - `connector` (string): Connector that did not answer fully.
    - `message` (string): What went wrong.
- `status` (string): Status of the cart (`open`, `ordered`, `discarded`). (one of `open`, `ordered`, `discarded`)
- `updatedAt` (string (date-time)): When the cart was last changed.
- `version` (integer): Raised by every change; a proposal is valid for one version.

Example 200 answer:

```json
{
  "createdAt": "2026-11-17T08:00:00Z",
  "createdBy": "anna.weber@muster-it.example",
  "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
  "kind": "manual",
  "lines": [
    {
      "articleNumber": "NW-2002",
      "description": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
      "manufacturer": "Kabelwerk",
      "mpn": "AP-WIFI6-C",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "masterdata": "KW-AP-WIFI6"
      },
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "unit": "STK"
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
      "manufacturer": "Nordlicht",
      "mpn": "HS-USB-ANC",
      "pinnedOffer": "egis:70044",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "quantity": 16,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "egis": "PCS400942",
        "masterdata": "NL-HS-USB-ANC"
      },
      "unit": "STK"
    }
  ],
  "name": "Wochenbestellung KW 47",
  "status": "open",
  "updatedAt": "2026-11-19T07:35:00Z",
  "version": 4
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Wochenbestellung KW 47"}'
```

## Put purchase recommendations into a cart (tenant:purchase-cart:write)

`POST /api/trade/v1/purchase-carts/{id}/recommendations`

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

One line per recommendation (article, quantity and ship-to from the sales order line); the recommendations
become `in_cart`. A recommendation already in this cart is left alone; one that is not open (in another cart,
ordered, dismissed) refuses the whole call (`409 recommendation_not_open`), a drop-ship one whose order has no
delivery address too (`422`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `recommendationIds` (array of string (uuid), required)

Example:

```json
{
  "recommendationIds": [
    "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
    "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02"
  ]
}
```

### Responses

- **200** The cart (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Unknown cart or recommendation. (`application/json`)
- **409** The cart does not allow it (`code`): `cart_not_open` (ordered or discarded), `recommendation_not_open`,
`line_ordered` (the line is on a purchase order), `nothing_to_order`, `no_proposal` (optimize first),
`proposal_stale` / `cart_changed` (optimize again), `accept_in_progress` (an optimization, accept or order of
the cart is running; retry shortly), `drop_ship_no_address` (a drop-ship order has no delivery address).
 (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the cart was created.
- `createdBy` (string): Who created the cart.
- `id` (string (uuid)): Id of the cart.
- `kind` (string): `auto`: the tenant's single automatic cart (`procurement.autoCart`), "Automatische Vorschläge". (one of `manual`, `auto`)
- `lines` (array of PurchaseCartLine): Lines of the cart.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the article.
  - `ean` (string): EAN (GTIN) of the article.
  - `flag` (string): Set when the sales order changed after the line went into the cart, e.g. `Kein Bedarf mehr`.
  - `id` (string (uuid)): Id of the cart line.
  - `manufacturer` (string): Manufacturer of the article.
  - `mpn` (string): Manufacturer part number.
  - `pinnedOffer` (string): Offer key the optimizer must use.
  - `poId` (string (uuid)): The purchase order the line is on.
  - `poLineId` (string (uuid)): Purchase order line the line became once accepted.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `recommendationId` (string (uuid)): Purchase recommendation the line came from.
  - `shipTo` (object): Customer address of a drop-ship line.
  - `shipToKind` (string): `stock` or `drop_ship`. (one of `stock`, `drop_ship`)
  - `sourceIdentifiers` (object): Article id per connector, e.g. `egis`: PCS number.
  - `sourceLineId` (string (uuid)): The sales order line (current revision).
  - `unit` (string): Unit of measure.
- `name` (string): Name of the cart.
- `proposal` (PurchaseCartProposal): The optimizer's split of the cart; amounts are net EUR cents.
  - `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
  - `acceptedAt` (string (date-time)): Set when every group is accepted.
  - `cartVersion` (integer): Version of the cart the proposal was computed for.
  - `id` (string): Id of the proposal.
  - `maxDays` (integer): Longest delivery time of the proposal in days.
  - `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
  - `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
  - `offers` (object): The offers used, per article key.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
  - `shipments` (array of object): One future purchase order each (offer key and ship-to).
    - `assignments` (array of object): Cart lines the shipment carries.
      - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
      - `lineId` (string (uuid)): Id of the cart line.
      - `offerKey` (string): Key of the distributor offer.
      - `priceCents` (integer): Unit price in cents.
      - `quantity` (number): Quantity assigned.
    - `days` (integer): Delivery days.
    - `dropShip` (boolean): The shipment goes straight to the customer.
    - `dropShipFeeCents` (integer): Drop-ship fee in cents.
    - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
    - `goodsCents` (integer): Goods value in cents.
    - `offerKey` (string): Key of the distributor offer the shipment uses.
    - `shipToKey` (string): `stock` or the drop-ship address key.
    - `shippingCents` (integer): Shipping cost in cents.
    - `supplierAddressId` (string): Masterdata address of the supplier.
    - `surchargeCents` (integer): Minimum-order surcharge in cents.
    - `totalCents` (integer): Total of the shipment in cents.
  - `totalCents` (integer): Total of the proposal in cents.
  - `unassigned` (array of object): Lines (or rests) no usable offer covers.
    - `lineId` (string (uuid)): Id of the cart line.
    - `missingQty` (number): Quantity no offer covers.
    - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
  - `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
    - `connector` (string): Connector that did not answer fully.
    - `message` (string): What went wrong.
- `status` (string): Status of the cart (`open`, `ordered`, `discarded`). (one of `open`, `ordered`, `discarded`)
- `updatedAt` (string (date-time)): When the cart was last changed.
- `version` (integer): Raised by every change; a proposal is valid for one version.

Example 200 answer:

```json
{
  "createdAt": "2026-11-17T08:00:00Z",
  "createdBy": "anna.weber@muster-it.example",
  "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
  "kind": "manual",
  "lines": [
    {
      "articleNumber": "NW-2002",
      "description": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
      "manufacturer": "Kabelwerk",
      "mpn": "AP-WIFI6-C",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "masterdata": "KW-AP-WIFI6"
      },
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "unit": "STK"
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
      "manufacturer": "Nordlicht",
      "mpn": "HS-USB-ANC",
      "pinnedOffer": "egis:70044",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "quantity": 16,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "egis": "PCS400942",
        "masterdata": "NL-HS-USB-ANC"
      },
      "unit": "STK"
    }
  ],
  "name": "Wochenbestellung KW 47",
  "status": "open",
  "updatedAt": "2026-11-19T07:35:00Z",
  "version": 4
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/recommendations' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"recommendationIds":["6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01","6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02"]}'
```

## Add an article to a cart (tenant:purchase-cart:write)

`POST /api/trade/v1/purchase-carts/{id}/lines`

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

A stock line from the distributor search. It needs a product id, MPN, EAN or article number and a positive quantity.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `quantity` (number, required): Quantity.
- `articleNumber` (string): Article number in masterdata.
- `description` (string): Description of the article.
- `ean` (string): EAN (GTIN) of the article.
- `manufacturer` (string): Manufacturer of the article.
- `mpn` (string): Manufacturer part number.
- `pinnedOffer` (string): Offer key the optimizer must use for the line.
- `productId` (string): Masterdata article (product) id.
- `sourceIdentifiers` (object): Distributor article numbers by distributor.
- `unit` (string): Unit of measure.

Example:

```json
{
  "description": "Toner 59X",
  "manufacturer": "HP",
  "mpn": "CF259X",
  "quantity": 5,
  "sourceIdentifiers": {
    "egis": "123456789"
  }
}
```

### Responses

- **200** The cart (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The cart does not allow it (`code`): `cart_not_open` (ordered or discarded), `recommendation_not_open`,
`line_ordered` (the line is on a purchase order), `nothing_to_order`, `no_proposal` (optimize first),
`proposal_stale` / `cart_changed` (optimize again), `accept_in_progress` (an optimization, accept or order of
the cart is running; retry shortly), `drop_ship_no_address` (a drop-ship order has no delivery address).
 (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the cart was created.
- `createdBy` (string): Who created the cart.
- `id` (string (uuid)): Id of the cart.
- `kind` (string): `auto`: the tenant's single automatic cart (`procurement.autoCart`), "Automatische Vorschläge". (one of `manual`, `auto`)
- `lines` (array of PurchaseCartLine): Lines of the cart.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the article.
  - `ean` (string): EAN (GTIN) of the article.
  - `flag` (string): Set when the sales order changed after the line went into the cart, e.g. `Kein Bedarf mehr`.
  - `id` (string (uuid)): Id of the cart line.
  - `manufacturer` (string): Manufacturer of the article.
  - `mpn` (string): Manufacturer part number.
  - `pinnedOffer` (string): Offer key the optimizer must use.
  - `poId` (string (uuid)): The purchase order the line is on.
  - `poLineId` (string (uuid)): Purchase order line the line became once accepted.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `recommendationId` (string (uuid)): Purchase recommendation the line came from.
  - `shipTo` (object): Customer address of a drop-ship line.
  - `shipToKind` (string): `stock` or `drop_ship`. (one of `stock`, `drop_ship`)
  - `sourceIdentifiers` (object): Article id per connector, e.g. `egis`: PCS number.
  - `sourceLineId` (string (uuid)): The sales order line (current revision).
  - `unit` (string): Unit of measure.
- `name` (string): Name of the cart.
- `proposal` (PurchaseCartProposal): The optimizer's split of the cart; amounts are net EUR cents.
  - `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
  - `acceptedAt` (string (date-time)): Set when every group is accepted.
  - `cartVersion` (integer): Version of the cart the proposal was computed for.
  - `id` (string): Id of the proposal.
  - `maxDays` (integer): Longest delivery time of the proposal in days.
  - `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
  - `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
  - `offers` (object): The offers used, per article key.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
  - `shipments` (array of object): One future purchase order each (offer key and ship-to).
    - `assignments` (array of object): Cart lines the shipment carries.
      - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
      - `lineId` (string (uuid)): Id of the cart line.
      - `offerKey` (string): Key of the distributor offer.
      - `priceCents` (integer): Unit price in cents.
      - `quantity` (number): Quantity assigned.
    - `days` (integer): Delivery days.
    - `dropShip` (boolean): The shipment goes straight to the customer.
    - `dropShipFeeCents` (integer): Drop-ship fee in cents.
    - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
    - `goodsCents` (integer): Goods value in cents.
    - `offerKey` (string): Key of the distributor offer the shipment uses.
    - `shipToKey` (string): `stock` or the drop-ship address key.
    - `shippingCents` (integer): Shipping cost in cents.
    - `supplierAddressId` (string): Masterdata address of the supplier.
    - `surchargeCents` (integer): Minimum-order surcharge in cents.
    - `totalCents` (integer): Total of the shipment in cents.
  - `totalCents` (integer): Total of the proposal in cents.
  - `unassigned` (array of object): Lines (or rests) no usable offer covers.
    - `lineId` (string (uuid)): Id of the cart line.
    - `missingQty` (number): Quantity no offer covers.
    - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
  - `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
    - `connector` (string): Connector that did not answer fully.
    - `message` (string): What went wrong.
- `status` (string): Status of the cart (`open`, `ordered`, `discarded`). (one of `open`, `ordered`, `discarded`)
- `updatedAt` (string (date-time)): When the cart was last changed.
- `version` (integer): Raised by every change; a proposal is valid for one version.

Example 200 answer:

```json
{
  "createdAt": "2026-11-17T08:00:00Z",
  "createdBy": "anna.weber@muster-it.example",
  "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
  "kind": "manual",
  "lines": [
    {
      "articleNumber": "NW-2002",
      "description": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
      "manufacturer": "Kabelwerk",
      "mpn": "AP-WIFI6-C",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "masterdata": "KW-AP-WIFI6"
      },
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "unit": "STK"
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
      "manufacturer": "Nordlicht",
      "mpn": "HS-USB-ANC",
      "pinnedOffer": "egis:70044",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "quantity": 16,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "egis": "PCS400942",
        "masterdata": "NL-HS-USB-ANC"
      },
      "unit": "STK"
    }
  ],
  "name": "Wochenbestellung KW 47",
  "status": "open",
  "updatedAt": "2026-11-19T07:35:00Z",
  "version": 4
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/lines' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Toner 59X","manufacturer":"HP","mpn":"CF259X","quantity":5,"sourceIdentifiers":{"egis":"123456789"}}'
```

## Remove a line from a cart (tenant:purchase-cart:write)

`DELETE /api/trade/v1/purchase-carts/{id}/lines/{lineId}`

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

The line's recommendation is open again; the automatic cart does not take it back until its need grows.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `lineId` | path | string (uuid) | yes |  |

### Responses

- **200** The cart (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The cart does not allow it (`code`): `cart_not_open` (ordered or discarded), `recommendation_not_open`,
`line_ordered` (the line is on a purchase order), `nothing_to_order`, `no_proposal` (optimize first),
`proposal_stale` / `cart_changed` (optimize again), `accept_in_progress` (an optimization, accept or order of
the cart is running; retry shortly), `drop_ship_no_address` (a drop-ship order has no delivery address).
 (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the cart was created.
- `createdBy` (string): Who created the cart.
- `id` (string (uuid)): Id of the cart.
- `kind` (string): `auto`: the tenant's single automatic cart (`procurement.autoCart`), "Automatische Vorschläge". (one of `manual`, `auto`)
- `lines` (array of PurchaseCartLine): Lines of the cart.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the article.
  - `ean` (string): EAN (GTIN) of the article.
  - `flag` (string): Set when the sales order changed after the line went into the cart, e.g. `Kein Bedarf mehr`.
  - `id` (string (uuid)): Id of the cart line.
  - `manufacturer` (string): Manufacturer of the article.
  - `mpn` (string): Manufacturer part number.
  - `pinnedOffer` (string): Offer key the optimizer must use.
  - `poId` (string (uuid)): The purchase order the line is on.
  - `poLineId` (string (uuid)): Purchase order line the line became once accepted.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `recommendationId` (string (uuid)): Purchase recommendation the line came from.
  - `shipTo` (object): Customer address of a drop-ship line.
  - `shipToKind` (string): `stock` or `drop_ship`. (one of `stock`, `drop_ship`)
  - `sourceIdentifiers` (object): Article id per connector, e.g. `egis`: PCS number.
  - `sourceLineId` (string (uuid)): The sales order line (current revision).
  - `unit` (string): Unit of measure.
- `name` (string): Name of the cart.
- `proposal` (PurchaseCartProposal): The optimizer's split of the cart; amounts are net EUR cents.
  - `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
  - `acceptedAt` (string (date-time)): Set when every group is accepted.
  - `cartVersion` (integer): Version of the cart the proposal was computed for.
  - `id` (string): Id of the proposal.
  - `maxDays` (integer): Longest delivery time of the proposal in days.
  - `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
  - `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
  - `offers` (object): The offers used, per article key.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
  - `shipments` (array of object): One future purchase order each (offer key and ship-to).
    - `assignments` (array of object): Cart lines the shipment carries.
      - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
      - `lineId` (string (uuid)): Id of the cart line.
      - `offerKey` (string): Key of the distributor offer.
      - `priceCents` (integer): Unit price in cents.
      - `quantity` (number): Quantity assigned.
    - `days` (integer): Delivery days.
    - `dropShip` (boolean): The shipment goes straight to the customer.
    - `dropShipFeeCents` (integer): Drop-ship fee in cents.
    - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
    - `goodsCents` (integer): Goods value in cents.
    - `offerKey` (string): Key of the distributor offer the shipment uses.
    - `shipToKey` (string): `stock` or the drop-ship address key.
    - `shippingCents` (integer): Shipping cost in cents.
    - `supplierAddressId` (string): Masterdata address of the supplier.
    - `surchargeCents` (integer): Minimum-order surcharge in cents.
    - `totalCents` (integer): Total of the shipment in cents.
  - `totalCents` (integer): Total of the proposal in cents.
  - `unassigned` (array of object): Lines (or rests) no usable offer covers.
    - `lineId` (string (uuid)): Id of the cart line.
    - `missingQty` (number): Quantity no offer covers.
    - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
  - `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
    - `connector` (string): Connector that did not answer fully.
    - `message` (string): What went wrong.
- `status` (string): Status of the cart (`open`, `ordered`, `discarded`). (one of `open`, `ordered`, `discarded`)
- `updatedAt` (string (date-time)): When the cart was last changed.
- `version` (integer): Raised by every change; a proposal is valid for one version.

Example 200 answer:

```json
{
  "createdAt": "2026-11-17T08:00:00Z",
  "createdBy": "anna.weber@muster-it.example",
  "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
  "kind": "manual",
  "lines": [
    {
      "articleNumber": "NW-2002",
      "description": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
      "manufacturer": "Kabelwerk",
      "mpn": "AP-WIFI6-C",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "masterdata": "KW-AP-WIFI6"
      },
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "unit": "STK"
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
      "manufacturer": "Nordlicht",
      "mpn": "HS-USB-ANC",
      "pinnedOffer": "egis:70044",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "quantity": 16,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "egis": "PCS400942",
        "masterdata": "NL-HS-USB-ANC"
      },
      "unit": "STK"
    }
  ],
  "name": "Wochenbestellung KW 47",
  "status": "open",
  "updatedAt": "2026-11-19T07:35:00Z",
  "version": 4
}
```

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/lines/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Change the quantity or pinned offer of a cart line (tenant:purchase-cart:write)

`PATCH /api/trade/v1/purchase-carts/{id}/lines/{lineId}`

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

Only fields sent are changed; `pinnedOffer` `""` removes the pin. A line already on a purchase order cannot be changed (`409 line_ordered`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `lineId` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `pinnedOffer` (string): Offer key `<source>:<distributorId>` the optimizer must use; empty removes the pin.
- `quantity` (number)

Example:

```json
{
  "pinnedOffer": "egis:70044",
  "quantity": 16
}
```

### Responses

- **200** The cart (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The cart does not allow it (`code`): `cart_not_open` (ordered or discarded), `recommendation_not_open`,
`line_ordered` (the line is on a purchase order), `nothing_to_order`, `no_proposal` (optimize first),
`proposal_stale` / `cart_changed` (optimize again), `accept_in_progress` (an optimization, accept or order of
the cart is running; retry shortly), `drop_ship_no_address` (a drop-ship order has no delivery address).
 (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the cart was created.
- `createdBy` (string): Who created the cart.
- `id` (string (uuid)): Id of the cart.
- `kind` (string): `auto`: the tenant's single automatic cart (`procurement.autoCart`), "Automatische Vorschläge". (one of `manual`, `auto`)
- `lines` (array of PurchaseCartLine): Lines of the cart.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the article.
  - `ean` (string): EAN (GTIN) of the article.
  - `flag` (string): Set when the sales order changed after the line went into the cart, e.g. `Kein Bedarf mehr`.
  - `id` (string (uuid)): Id of the cart line.
  - `manufacturer` (string): Manufacturer of the article.
  - `mpn` (string): Manufacturer part number.
  - `pinnedOffer` (string): Offer key the optimizer must use.
  - `poId` (string (uuid)): The purchase order the line is on.
  - `poLineId` (string (uuid)): Purchase order line the line became once accepted.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `recommendationId` (string (uuid)): Purchase recommendation the line came from.
  - `shipTo` (object): Customer address of a drop-ship line.
  - `shipToKind` (string): `stock` or `drop_ship`. (one of `stock`, `drop_ship`)
  - `sourceIdentifiers` (object): Article id per connector, e.g. `egis`: PCS number.
  - `sourceLineId` (string (uuid)): The sales order line (current revision).
  - `unit` (string): Unit of measure.
- `name` (string): Name of the cart.
- `proposal` (PurchaseCartProposal): The optimizer's split of the cart; amounts are net EUR cents.
  - `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
  - `acceptedAt` (string (date-time)): Set when every group is accepted.
  - `cartVersion` (integer): Version of the cart the proposal was computed for.
  - `id` (string): Id of the proposal.
  - `maxDays` (integer): Longest delivery time of the proposal in days.
  - `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
  - `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
  - `offers` (object): The offers used, per article key.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
  - `shipments` (array of object): One future purchase order each (offer key and ship-to).
    - `assignments` (array of object): Cart lines the shipment carries.
      - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
      - `lineId` (string (uuid)): Id of the cart line.
      - `offerKey` (string): Key of the distributor offer.
      - `priceCents` (integer): Unit price in cents.
      - `quantity` (number): Quantity assigned.
    - `days` (integer): Delivery days.
    - `dropShip` (boolean): The shipment goes straight to the customer.
    - `dropShipFeeCents` (integer): Drop-ship fee in cents.
    - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
    - `goodsCents` (integer): Goods value in cents.
    - `offerKey` (string): Key of the distributor offer the shipment uses.
    - `shipToKey` (string): `stock` or the drop-ship address key.
    - `shippingCents` (integer): Shipping cost in cents.
    - `supplierAddressId` (string): Masterdata address of the supplier.
    - `surchargeCents` (integer): Minimum-order surcharge in cents.
    - `totalCents` (integer): Total of the shipment in cents.
  - `totalCents` (integer): Total of the proposal in cents.
  - `unassigned` (array of object): Lines (or rests) no usable offer covers.
    - `lineId` (string (uuid)): Id of the cart line.
    - `missingQty` (number): Quantity no offer covers.
    - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
  - `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
    - `connector` (string): Connector that did not answer fully.
    - `message` (string): What went wrong.
- `status` (string): Status of the cart (`open`, `ordered`, `discarded`). (one of `open`, `ordered`, `discarded`)
- `updatedAt` (string (date-time)): When the cart was last changed.
- `version` (integer): Raised by every change; a proposal is valid for one version.

Example 200 answer:

```json
{
  "createdAt": "2026-11-17T08:00:00Z",
  "createdBy": "anna.weber@muster-it.example",
  "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
  "kind": "manual",
  "lines": [
    {
      "articleNumber": "NW-2002",
      "description": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
      "manufacturer": "Kabelwerk",
      "mpn": "AP-WIFI6-C",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "masterdata": "KW-AP-WIFI6"
      },
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "unit": "STK"
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
      "manufacturer": "Nordlicht",
      "mpn": "HS-USB-ANC",
      "pinnedOffer": "egis:70044",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "quantity": 16,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "egis": "PCS400942",
        "masterdata": "NL-HS-USB-ANC"
      },
      "unit": "STK"
    }
  ],
  "name": "Wochenbestellung KW 47",
  "status": "open",
  "updatedAt": "2026-11-19T07:35:00Z",
  "version": 4
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/lines/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"pinnedOffer":"egis:70044","quantity":16}'
```

## Import a shared EGIS cart into a purchase cart (tenant:purchase-cart:write)

`POST /api/trade/v1/purchase-carts/{id}/import-egis`

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

Adds the positions of the tenant's shared EGIS cart `(global) <name>` as stock lines (the PCS number as EGIS identifier, no pin). The EGIS cart is not changed.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `name` (string, required): EGIS cart label without the `(global)` prefix.

Example:

```json
{
  "name": "Einkauf"
}
```

### Responses

- **200** The cart (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The cart does not allow it (`code`): `cart_not_open` (ordered or discarded), `recommendation_not_open`,
`line_ordered` (the line is on a purchase order), `nothing_to_order`, `no_proposal` (optimize first),
`proposal_stale` / `cart_changed` (optimize again), `accept_in_progress` (an optimization, accept or order of
the cart is running; retry shortly), `drop_ship_no_address` (a drop-ship order has no delivery address).
 (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** EGIS is not available in this installation. (`application/json`)

Fields of the 200 answer:

- `createdAt` (string (date-time)): When the cart was created.
- `createdBy` (string): Who created the cart.
- `id` (string (uuid)): Id of the cart.
- `kind` (string): `auto`: the tenant's single automatic cart (`procurement.autoCart`), "Automatische Vorschläge". (one of `manual`, `auto`)
- `lines` (array of PurchaseCartLine): Lines of the cart.
  - `articleNumber` (string): Article number in masterdata.
  - `description` (string): Description of the article.
  - `ean` (string): EAN (GTIN) of the article.
  - `flag` (string): Set when the sales order changed after the line went into the cart, e.g. `Kein Bedarf mehr`.
  - `id` (string (uuid)): Id of the cart line.
  - `manufacturer` (string): Manufacturer of the article.
  - `mpn` (string): Manufacturer part number.
  - `pinnedOffer` (string): Offer key the optimizer must use.
  - `poId` (string (uuid)): The purchase order the line is on.
  - `poLineId` (string (uuid)): Purchase order line the line became once accepted.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity.
  - `recommendationId` (string (uuid)): Purchase recommendation the line came from.
  - `shipTo` (object): Customer address of a drop-ship line.
  - `shipToKind` (string): `stock` or `drop_ship`. (one of `stock`, `drop_ship`)
  - `sourceIdentifiers` (object): Article id per connector, e.g. `egis`: PCS number.
  - `sourceLineId` (string (uuid)): The sales order line (current revision).
  - `unit` (string): Unit of measure.
- `name` (string): Name of the cart.
- `proposal` (PurchaseCartProposal): The optimizer's split of the cart; amounts are net EUR cents.
  - `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
  - `acceptedAt` (string (date-time)): Set when every group is accepted.
  - `cartVersion` (integer): Version of the cart the proposal was computed for.
  - `id` (string): Id of the proposal.
  - `maxDays` (integer): Longest delivery time of the proposal in days.
  - `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
  - `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
  - `offers` (object): The offers used, per article key.
  - `optimizedAt` (string (date-time)): When the proposal was computed.
  - `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
  - `shipments` (array of object): One future purchase order each (offer key and ship-to).
    - `assignments` (array of object): Cart lines the shipment carries.
      - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
      - `lineId` (string (uuid)): Id of the cart line.
      - `offerKey` (string): Key of the distributor offer.
      - `priceCents` (integer): Unit price in cents.
      - `quantity` (number): Quantity assigned.
    - `days` (integer): Delivery days.
    - `dropShip` (boolean): The shipment goes straight to the customer.
    - `dropShipFeeCents` (integer): Drop-ship fee in cents.
    - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
    - `goodsCents` (integer): Goods value in cents.
    - `offerKey` (string): Key of the distributor offer the shipment uses.
    - `shipToKey` (string): `stock` or the drop-ship address key.
    - `shippingCents` (integer): Shipping cost in cents.
    - `supplierAddressId` (string): Masterdata address of the supplier.
    - `surchargeCents` (integer): Minimum-order surcharge in cents.
    - `totalCents` (integer): Total of the shipment in cents.
  - `totalCents` (integer): Total of the proposal in cents.
  - `unassigned` (array of object): Lines (or rests) no usable offer covers.
    - `lineId` (string (uuid)): Id of the cart line.
    - `missingQty` (number): Quantity no offer covers.
    - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
  - `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
    - `connector` (string): Connector that did not answer fully.
    - `message` (string): What went wrong.
- `status` (string): Status of the cart (`open`, `ordered`, `discarded`). (one of `open`, `ordered`, `discarded`)
- `updatedAt` (string (date-time)): When the cart was last changed.
- `version` (integer): Raised by every change; a proposal is valid for one version.

Example 200 answer:

```json
{
  "createdAt": "2026-11-17T08:00:00Z",
  "createdBy": "anna.weber@muster-it.example",
  "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
  "kind": "manual",
  "lines": [
    {
      "articleNumber": "NW-2002",
      "description": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
      "manufacturer": "Kabelwerk",
      "mpn": "AP-WIFI6-C",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "masterdata": "KW-AP-WIFI6"
      },
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "unit": "STK"
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
      "manufacturer": "Nordlicht",
      "mpn": "HS-USB-ANC",
      "pinnedOffer": "egis:70044",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "quantity": 16,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "egis": "PCS400942",
        "masterdata": "NL-HS-USB-ANC"
      },
      "unit": "STK"
    }
  ],
  "name": "Wochenbestellung KW 47",
  "status": "open",
  "updatedAt": "2026-11-19T07:35:00Z",
  "version": 4
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/import-egis' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Einkauf"}'
```

## Optimize a purchase cart (tenant:purchase-cart:write)

`POST /api/trade/v1/purchase-carts/{id}/optimize`

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

Gathers the offers of every enabled distributor connector (and the supplier prices of masterdata articles) for
the lines not ordered yet and splits them by the lowest landed cost (goods plus shipping, surcharges and drop-ship
fees per shipment, `procurement` settings). The proposal is stored at the cart for its current `version`; a
connector that failed is named in `warnings`, a line no usable offer covers in `unassigned`. Accept it with
`acceptPurchaseCartProposal` before the offers expire (`procurement.offerTtlMinutes`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The proposal (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The cart does not allow it (`code`): `cart_not_open` (ordered or discarded), `recommendation_not_open`,
`line_ordered` (the line is on a purchase order), `nothing_to_order`, `no_proposal` (optimize first),
`proposal_stale` / `cart_changed` (optimize again), `accept_in_progress` (an optimization, accept or order of
the cart is running; retry shortly), `drop_ship_no_address` (a drop-ship order has no delivery address).
 (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** Offers are not available in this installation. (`application/json`)

Fields of the 200 answer:

- `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
- `acceptedAt` (string (date-time)): Set when every group is accepted.
- `cartVersion` (integer): Version of the cart the proposal was computed for.
- `id` (string): Id of the proposal.
- `maxDays` (integer): Longest delivery time of the proposal in days.
- `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
- `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
- `offers` (object): The offers used, per article key.
- `optimizedAt` (string (date-time)): When the proposal was computed.
- `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
- `shipments` (array of object): One future purchase order each (offer key and ship-to).
  - `assignments` (array of object): Cart lines the shipment carries.
    - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
    - `lineId` (string (uuid)): Id of the cart line.
    - `offerKey` (string): Key of the distributor offer.
    - `priceCents` (integer): Unit price in cents.
    - `quantity` (number): Quantity assigned.
  - `days` (integer): Delivery days.
  - `dropShip` (boolean): The shipment goes straight to the customer.
  - `dropShipFeeCents` (integer): Drop-ship fee in cents.
  - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
  - `goodsCents` (integer): Goods value in cents.
  - `offerKey` (string): Key of the distributor offer the shipment uses.
  - `shipToKey` (string): `stock` or the drop-ship address key.
  - `shippingCents` (integer): Shipping cost in cents.
  - `supplierAddressId` (string): Masterdata address of the supplier.
  - `surchargeCents` (integer): Minimum-order surcharge in cents.
  - `totalCents` (integer): Total of the shipment in cents.
- `totalCents` (integer): Total of the proposal in cents.
- `unassigned` (array of object): Lines (or rests) no usable offer covers.
  - `lineId` (string (uuid)): Id of the cart line.
  - `missingQty` (number): Quantity no offer covers.
  - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
- `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
  - `connector` (string): Connector that did not answer fully.
  - `message` (string): What went wrong.

Example 200 answer:

```json
{
  "cartVersion": 4,
  "id": "c4f1a2b3-wk47-optimum",
  "maxDays": 2,
  "method": "exact",
  "naiveTotalCents": 222650,
  "offers": {
    "HW-1007": [
      {
        "available": 140,
        "days": 1,
        "distributorId": "70044",
        "distributorName": "Nordlicht IT-Distribution GmbH",
        "fetchedAt": "2026-11-19T07:39:58Z",
        "key": "egis:70044",
        "priceCents": 7900,
        "source": "egis",
        "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
        "supplierArticleNumber": "NL-HS-USB-ANC",
        "supplierName": "Nordlicht IT-Distribution GmbH"
      }
    ],
    "NW-2002": [
      {
        "available": null,
        "days": 2,
        "distributorId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
        "fetchedAt": "2026-11-19T07:39:58Z",
        "key": "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
        "priceCents": 15900,
        "source": "masterdata",
        "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
        "supplierArticleNumber": "KW-AP-WIFI6",
        "supplierName": "Kabelwerk Süd GmbH"
      }
    ]
  },
  "optimizedAt": "2026-11-19T07:40:00Z",
  "savingsCents": 0,
  "shipments": [
    {
      "assignments": [
        {
          "lineCents": 95400,
          "lineId": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
          "offerKey": "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
          "priceCents": 15900,
          "quantity": 6
        }
      ],
      "days": 2,
      "dropShip": false,
      "dropShipFeeCents": 0,
      "freightQuoted": false,
      "goodsCents": 95400,
      "offerKey": "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
      "shipToKey": "stock",
      "shippingCents": 0,
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
      "surchargeCents": 0,
      "totalCents": 95400
    },
    {
      "assignments": [
        {
          "lineCents": 126400,
          "lineId": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
          "offerKey": "egis:70044",
          "priceCents": 7900,
          "quantity": 16
        }
      ],
      "days": 1,
      "dropShip": false,
      "dropShipFeeCents": 0,
      "freightQuoted": false,
      "goodsCents": 126400,
      "offerKey": "egis:70044",
      "shipToKey": "stock",
      "shippingCents": 850,
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "surchargeCents": 0,
      "totalCents": 127250
    }
  ],
  "totalCents": 222650,
  "unassigned": [],
  "warnings": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/optimize' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Accept the proposal of a cart and create its purchase orders (tenant:purchase-cart:write)

`POST /api/trade/v1/purchase-carts/{id}/accept`

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

Creates one `draft` purchase order (`BE-<year>-<nnnnn>`) per supplier and ship-to of the proposal, linked to the
sales order lines; drop-ship orders carry the customer's address. A line whose sales order needs less now is
capped and listed in `capped`; a line nothing needs any more is flagged and its recommendation is open again.
The proposal must be the cart's current one (`proposal_stale`), the cart unchanged since it was optimized
(`cart_changed`) and its offers younger than `procurement.offerTtlMinutes`. Accepting again returns the same
purchase orders (`existing: true`); after an interrupted accept (`409 accept_incomplete`, the created orders in
`details.purchaseOrders`) accepting again creates only the missing ones. Publishes `trade.purchaseorder.created` per
order and `trade.purchase_cart.accepted` once orders were created.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `proposalId` (string, required)

Example:

```json
{
  "proposalId": "c4f1a2b3-wk47-optimum"
}
```

### Responses

- **200** The purchase orders of the proposal (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** See `PurchaseCartConflict`; an interrupted accept (`accept_incomplete`, or the conflict that stopped it) also lists the purchase orders created so far. (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** Creating purchase orders is not available in this installation. (`application/json`)

Fields of the 200 answer:

- `capped` (array of object): Lines ordered with less than the proposal said, because their sales order needs less now.
  - `lineId` (string (uuid)): Id of the cart line.
  - `ordered` (number): Quantity ordered.
  - `requested` (number): Quantity the proposal said.
- `existing` (boolean): Everything existed already (a repeated accept).
- `purchaseOrders` (array of PurchaseOrder): Purchase orders of the proposal.
  - `createdAt` (string (date-time)): When the purchase order was created.
  - `currency` (string): Currency (ISO 4217).
  - `dropShip` (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
  - `egis` (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
    - `cargoInsurance` (number): Cargo insurance charged.
    - `confirmations` (array of object): Order confirmations of the distributor.
      - `date` (string (date)): Date of the confirmation.
      - `distributorOrderNumber` (string): The distributor's order number.
      - `id` (integer): EGIS id of the confirmation.
      - `lines` (array of object): Confirmed lines.
        - `deliveryDate` (string (date)): Expected delivery date.
        - `position` (integer): Purchase order line.
        - `quantity` (number): Planned delivery quantity.
        - `supplierArticleNumber` (string): The distributor's article number.
        - `unitPrice` (number): Confirmed net unit price.
    - `deliveryNotes` (array of object): Delivery notes of the distributor.
      - `date` (string (date)): Date of the delivery note.
      - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
      - `id` (string): EGIS delivery note id.
      - `lines` (array of object): Delivered lines.
        - `description` (string): Description of the article.
        - `ean` (string): EAN (GTIN) of the article.
        - `mpn` (string): Manufacturer part number.
        - `position` (integer): Position number of the line.
        - `quantity` (number): Quantity delivered.
        - `serialNumbers` (array of string): Serial numbers.
        - `supplierArticleNumber` (string): The distributor's article number.
        - `unit` (string): Unit of measure.
      - `number` (string): The distributor's delivery note number.
      - `packages` (array of object): Packages of the shipment.
        - `number` (string): Tracking number of the package.
        - `trackingUrl` (string (uri)): Tracking link of the package.
      - `shipper` (string): Carrier of the shipment.
    - `distributorId` (string): EGIS distributor number.
    - `distributorName` (string): Name of the distributor the order went to.
    - `distributorOrderNumber` (string): The distributor's own order number (also stored as the external number of the order when empty).
    - `freightCharge` (number): Freight including additional charges.
    - `invoices` (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
      - `currency` (string): Currency (ISO 4217).
      - `date` (string (date)): Invoice date.
      - `grossAmount` (number): Gross amount of the invoice.
      - `id` (integer): EGIS id of the invoice.
      - `lines` (array of object): Invoiced lines.
        - `description` (string): Description of the article.
        - `netTotal` (number): Net total of the line.
        - `position` (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
        - `quantity` (number): Quantity invoiced.
        - `supplierArticleNumber` (string): The distributor's article number.
        - `taxRate` (number): Percent.
        - `unitPrice` (number): Net unit price.
      - `netAmount` (number): Net amount of the invoice.
      - `number` (string): The distributor's invoice number.
      - `vatAmount` (number): VAT amount of the invoice.
    - `link` (string (uri)): The order in the EGIS web application.
    - `orderDate` (string (date)): Order date at EGIS.
    - `orderNumber` (string): EGIS order number (leading zeros kept); invoices naming it find the order.
    - `paymentMethod` (string): Payment method of the order at EGIS.
    - `sentAt` (string (date-time)): When the order was sent to EGIS.
    - `smallQuantitiesMarkup` (number): Small-quantity markup charged.
    - `statusCode` (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of `-1`, `0`, `10`, `20`, `30`, `40`, `50`)
    - `statusText` (string): Status text of EGIS.
  - `goodsReceipts` (array of object): Goods receipts of the purchase order.
    - `grNumber` (string): Number of the goods receipt.
    - `id` (string (uuid)): Id of the goods receipt.
    - `receivedAt` (string (date-time)): When the goods were received.
    - `status` (string): Status of the goods receipt.
  - `id` (string (uuid)): Id of the purchase order.
  - `lines` (array of POLine): Empty in lists.
    - `articleNumber` (string): Article number in masterdata.
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `id` (string (uuid)): Id of the purchase order line.
    - `invoicedQty` (number): Always 0.
    - `mpn` (string): Manufacturer part number.
    - `orderedQty` (number): Quantity ordered.
    - `pcsNumber` (string): EGIS PCS number of the article (purchase cart orders).
    - `position` (integer): Position number of the line.
    - `productId` (string (uuid)): Masterdata article (product) id.
    - `receivedQty` (number): Quantity received.
    - `sourceLineId` (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
    - `supplierArticleNumber` (string): The distributor's article number of the offer the purchase cart chose.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
  - `netTotal` (number): Net total of the purchase order.
  - `orderDate` (string (date)): Order date.
  - `poNumber` (string): Number of the purchase order.
  - `sourceOrders` (array of object): The sales orders the lines were bought for.
    - `id` (string (uuid)): Id of the sales order.
    - `number` (string): Number of the sales order.
  - `sourcing` (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
    - `cartId` (string (uuid)): Purchase cart the order was made from.
    - `distributorId` (string): Distributor the cart optimizer chose.
    - `goodsCents` (integer): Goods value of the shipment in cents.
    - `offerKey` (string): Key of the distributor offer.
    - `offerKeys` (array of string): Every offer key of the order when several share the supplier.
    - `optimizedAt` (string (date-time)): When the proposal was computed.
    - `priceCents` (integer): Landed cost (goods and shipment costs) in euro cents.
    - `proposalId` (string (uuid)): Proposal of the cart the order was made from.
    - `shippingCents` (integer): Shipping cost of the shipment in cents.
    - `source` (string): Offer source: egis, ingram, infinigate or masterdata.
  - `status` (PurchaseOrderStatus): (one of `draft`, `open`, `partially_received`, `received`, `closed`, `cancelled`)
  - `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
  - `supplierOrder` (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
    - `attemptedAt` (string (date-time)): When the last API send started.
    - `awaitingDocuments` (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
    - `channel` (string): How the order went out; `manual`: ordered by other means and recorded. (one of `ingram`, `infinigate`, `mail`, `manual`)
    - `comment` (string): Remark of the last send; a mail sent again without one repeats it.
    - `error` (string): Why the last send or refresh failed.
    - `expectedDeliveryDate` (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
    - `followError` (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
    - `invoices` (array of object): Invoices the supplier reported.
      - `date` (string (date)): Invoice date.
      - `grossTotal` (number): Gross total.
      - `netTotal` (number): Net total.
      - `number` (string): Invoice number of the supplier.
    - `lastFollowedAt` (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
    - `lineMap` (object): Supplier line number → purchase order line id.
    - `orderNumber` (string): The supplier's order number (also stored as the external number of the order when empty).
    - `recipient` (string (email)): Where the mail went (mail).
    - `rejectedLines` (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
      - `lineId` (string (uuid)): Id of the purchase order line.
      - `reason` (string): The supplier's reason.
      - `supplierLineNumber` (string): The line number the supplier got (key of `lineMap`).
    - `related` (array of string): Further order numbers when the supplier split the order.
    - `rematchPending` (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
    - `requestedDeliveryDate` (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
    - `revision` (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
    - `sentAt` (string (date-time)): When the order was sent.
    - `sentLines` (object): What an API send asked for, by supplier line number (key of `lineMap`); a lost answer is compared with it.
    - `shipments` (array of object): Shipments the supplier reported.
      - `carrier` (string): Carrier of the shipment.
      - `deliveryNoteId` (string (uuid)): The inbound delivery note made from it.
      - `handledManually` (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
      - `id` (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
      - `invoiceNumber` (string): The supplier's invoice of the shipment.
      - `lines` (array of object): Lines of the shipment.
        - `lineId` (string (uuid)): Id of the purchase order line.
        - `quantity` (number): Quantity shipped.
        - `serialNumbers` (array of string): Serial numbers.
      - `number` (string): The supplier's delivery note number.
      - `shippedAt` (string (date-time)): When it was shipped.
      - `subOrder` (string): The supplier's sub order of the shipment (Ingram).
      - `takeoverAttempts` (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
      - `takeoverError` (string): Why the last hand-over failed.
      - `trackingNumber` (string): Tracking number of the carrier.
      - `trackingUrl` (string): Tracking link of the carrier.
    - `shipmentsMissingSince` (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
    - `state` (string): State at the supplier (`sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`). (one of `sending`, `sent`, `confirmed`, `partially_shipped`, `shipped`, `cancelled`, `failed`)
    - `statusText` (string): The supplier's status text.
  - `updatedAt` (string (date-time)): When the purchase order was last changed.

Example 200 answer:

```json
{
  "capped": [],
  "existing": false,
  "purchaseOrders": [
    {
      "createdAt": "2026-11-19T07:42:00Z",
      "currency": "EUR",
      "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d74",
      "netTotal": 954,
      "orderDate": "2026-11-19",
      "poNumber": "BE-2026-00074",
      "sourceOrders": [
        {
          "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
          "number": "AB-2026-0143"
        }
      ],
      "sourcing": {
        "cartId": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
        "distributorId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
        "goodsCents": 95400,
        "offerKey": "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
        "optimizedAt": "2026-11-19T07:40:00Z",
        "priceCents": 95400,
        "shippingCents": 0,
        "source": "masterdata"
      },
      "status": "draft",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
      "updatedAt": "2026-11-19T07:42:00Z"
    },
    {
      "createdAt": "2026-11-19T07:42:01Z",
      "currency": "EUR",
      "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d75",
      "netTotal": 1264,
      "orderDate": "2026-11-19",
      "poNumber": "BE-2026-00075",
      "sourcing": {
        "cartId": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
        "distributorId": "70044",
        "goodsCents": 126400,
        "offerKey": "egis:70044",
        "optimizedAt": "2026-11-19T07:40:00Z",
        "priceCents": 127250,
        "shippingCents": 850,
        "source": "egis"
      },
      "status": "draft",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "updatedAt": "2026-11-19T07:42:01Z"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/accept' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"proposalId":"c4f1a2b3-wk47-optimum"}'
```

## Send the cart's purchase orders to their suppliers (tenant:purchase-cart:write plus the channel's send permission)

`POST /api/trade/v1/purchase-carts/{id}/order`

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

Sends every draft, unsent purchase order of the cart through the channel of its offer: EGIS orders through EGIS
(`tenant:egis-order:send` as well), Ingram offers through the Ingram API and masterdata supplier prices by mail
to the supplier's order address (both `tenant:purchase-order:send` as well, like `POST /purchase-orders/{id}/send`);
a channel without a send permission of its own is never used from here. Each order gets an outcome; a failure
(missing data, no channel for the distributor yet – Infinigate –, missing permission) is reported in `error`
and does not stop the others. Sent orders are not sent again.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** One outcome per purchase order (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The cart does not allow it (`code`): `cart_not_open` (ordered or discarded), `recommendation_not_open`,
`line_ordered` (the line is on a purchase order), `nothing_to_order`, `no_proposal` (optimize first),
`proposal_stale` / `cart_changed` (optimize again), `accept_in_progress` (an optimization, accept or order of
the cart is running; retry shortly), `drop_ship_no_address` (a drop-ship order has no delivery address).
 (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** Purchase orders are not available in this installation. (`application/json`)

Fields of the 200 answer:

- `outcomes` (array of PurchaseCartSendOutcome)
  - `channel` (string): The offer source, e.g. `egis`.
  - `error` (string): Why it was not sent (German); absent when sent.
  - `poId` (string (uuid)): Id of the purchase order.
  - `poNumber` (string): Number of the purchase order.

Example 200 answer:

```json
{
  "outcomes": [
    {
      "channel": "egis",
      "poId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d75",
      "poNumber": "BE-2026-00075"
    },
    {
      "channel": "masterdata",
      "error": "Für Kabelwerk Süd GmbH ist keine Bestelladresse hinterlegt (Stammdaten › Lieferant › Bestell-E-Mail).",
      "poId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d74",
      "poNumber": "BE-2026-00074"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/order' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get what a sales order has ordered, received and delivered (tenant:trade:sales:read)

`GET /api/trade/v1/sales/order-confirmations/{id}/supply`

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

Per orderable line of the order (summed over its revisions): the quantity, what linked purchase order lines
order and received, and what was delivered (outbound delivery notes plus drop-ship receipts); and every purchase
order linked to one of its lines. Computed when read.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Supply of the order (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not an order of the tenant. (`application/json`)

Fields of the 200 answer:

- `complete` (boolean): Every line is delivered, or a stock line is received in full.
- `lines` (array of object): Supply per order line.
  - `deliveredQty` (number): Quantity of the linked delivery note lines (not cancelled) plus what drop-ship purchase orders received.
  - `deliveryDate` (string (date-time)): The order's delivery date.
  - `dropShip` (boolean): The line is delivered by drop shipment.
  - `orderId` (string (uuid)): Id of the sales order.
  - `orderLineId` (string (uuid)): Id of the order line.
  - `orderedQty` (number): Quantity of the linked purchase order lines.
  - `overOrderedQty` (number): Ordered beyond the order line: max(0, `orderedQty` − `quantity`).
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Quantity of the order line.
  - `receivedQty` (number): Goods receipt quantity of the linked purchase order lines.
  - `rootLineId` (string (uuid)): The first revision of the line.
- `orderId` (string (uuid)): Id of the sales order.
- `purchaseOrders` (array of LinkedPurchaseOrder): Purchase orders linked to the order.
  - `dropShip` (boolean): The supplier delivers straight to the customer.
  - `id` (string (uuid)): Id of the purchase order.
  - `poNumber` (string): Number of the purchase order.
  - `status` (string): Status of the purchase order.
  - `supplierAddressId` (string): Masterdata address of the supplier.
  - `supplierName` (string): Name of the supplier.

Example 200 answer:

```json
{
  "complete": false,
  "lines": [
    {
      "deliveredQty": 6,
      "deliveryDate": "2026-11-24T00:00:00Z",
      "dropShip": false,
      "orderId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "orderLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "orderedQty": 6,
      "overOrderedQty": 0,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "receivedQty": 6,
      "rootLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01"
    },
    {
      "deliveredQty": 1,
      "deliveryDate": "2026-11-24T00:00:00Z",
      "dropShip": false,
      "orderId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "orderLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e02",
      "orderedQty": 0,
      "overOrderedQty": 0,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
      "quantity": 1,
      "receivedQty": 0,
      "rootLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e02"
    }
  ],
  "orderId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
  "purchaseOrders": [
    {
      "dropShip": false,
      "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d01",
      "poNumber": "BE-2026-0061",
      "status": "received",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
      "supplierName": "Kabelwerk Süd GmbH"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/sales/order-confirmations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/supply' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Cancel a sales order with its purchase order drafts (tenant:purchase-cart:write)

`POST /api/trade/v1/sales/order-confirmations/{id}/cancel`

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

In one transaction: the order becomes `cancelled`; its draft purchase orders whose every line was bought for
this order are cancelled; its open purchase recommendations are deleted; its cart lines without purchase order
are flagged `Auftrag storniert` (they stay in the cart, the cart's proposal is dropped). Purchase orders that
are open or further, or drafts that also serve other orders, are listed back (`openPurchaseOrders`) – the
buyer decides. Earlier revisions of the order count as the order. Writes `trade.order.cancelled`.
Idempotent: cancelling a cancelled order answers it unchanged and writes nothing.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The cancelled order and what happened to its purchasing (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not an order of the tenant. (`application/json`)
- **409** `order_superseded` (the order has a newer revision; cancel that one), `order_closed` (the order is in a
final status: done, delivered, shipped, revoked, expired or converted) or `order_busy` (lines of the order
were moving into carts meanwhile; try again).
 (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `cancelledPurchaseOrders` (array of LinkedPurchaseOrder): Drafts that served only this order and were cancelled with it.
  - `dropShip` (boolean): The supplier delivers straight to the customer.
  - `id` (string (uuid)): Id of the purchase order.
  - `poNumber` (string): Number of the purchase order.
  - `status` (string): Status of the purchase order.
  - `supplierAddressId` (string): Masterdata address of the supplier.
  - `supplierName` (string): Name of the supplier.
- `flaggedCartLines` (integer): Cart lines of the order flagged "Auftrag storniert".
- `openPurchaseOrders` (array of LinkedPurchaseOrder): Purchase orders still active for the order (open or further, drafts that also serve other orders or are locked by a workflow); the buyer decides about them.
  - `dropShip` (boolean): The supplier delivers straight to the customer.
  - `id` (string (uuid)): Id of the purchase order.
  - `poNumber` (string): Number of the purchase order.
  - `status` (string): Status of the purchase order.
  - `supplierAddressId` (string): Masterdata address of the supplier.
  - `supplierName` (string): Name of the supplier.
- `order` (Transaction)
  - `addressId` (string (uuid)): Masterdata address of the partner.
  - `createdAt` (string (date-time), read-only): When the transaction was created.
  - `currency` (string): ISO 4217; EUR when empty.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `deliveryDate` (string (date-time)): Delivery date.
  - `documentDate` (string (date-time)): Today when empty on create.
  - `documentRefId` (string (uuid)): DMS document of the transaction.
  - `dueDate` (string (date-time)): Due date.
  - `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
  - `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
  - `exchangeRate` (number): 1 when empty.
  - `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
  - `footerText` (string): Text printed below the lines.
  - `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
  - `grossTotal` (number, read-only): Gross total, computed from the lines.
  - `headerText` (string): Text printed above the lines.
  - `id` (string (uuid), read-only): Id of the transaction.
  - `items` (array of TransactionLine): Lines; on update they replace all lines when present.
    - `name` (string, required): Name of the article or line.
    - `quantity` (number, required): Quantity.
    - `articleNumber` (string): Article number in masterdata.
    - `createdAt` (string (date-time), read-only): When the line was created.
    - `description` (string): Description of the line.
    - `discountPercent` (number): Discount in percent.
    - `ean` (string): EAN (GTIN) of the article.
    - `id` (string (uuid), read-only): Id of the line.
    - `isOptional` (boolean): The line is optional (position type `optional`).
    - `isSelected` (boolean): Selected optional lines count in the totals.
    - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
    - `mpn` (string): Manufacturer part number.
    - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
    - `positionNumber` (integer, read-only): Set from the order of `items`.
    - `positionType` (PositionType)
    - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
    - `productId` (string (uuid)): Masterdata article (product) id.
    - `sortOrder` (integer): Sort order (ascending).
    - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
    - `taxRate` (number): Percent.
    - `totalPriceGross` (number, read-only): Gross total of the line, computed.
    - `totalPriceNet` (number, read-only): Net total of the line, computed.
    - `transactionId` (string (uuid), read-only): Id of the transaction.
    - `unit` (string): Unit of measure.
    - `unitPriceNet` (number): Negative for a credit position.
    - `updatedAt` (string (date-time), read-only): When the line was last changed.
  - `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number, read-only): Computed from the lines.
  - `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
  - `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
  - `partnerReference` (string): The partner's order reference (BT-13).
  - `paymentMethodCode` (string): Code of the payment method in masterdata.
  - `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
  - `paymentTermsText` (string): Payment terms as printed text.
  - `predecessorId` (string (uuid)): Previous version of the same document.
  - `recipientAddress` (object): Address snapshot of the partner.
  - `recipientCompany` (string): Company of the recipient.
  - `recipientEmail` (string): E-mail of the recipient.
  - `recipientName` (string): Name of the recipient.
  - `skontoDays1` (integer): Days of the first cash discount.
  - `skontoDays2` (integer): Days of the second cash discount.
  - `skontoRate1` (number): Rate in percent of the first cash discount.
  - `skontoRate2` (number): Rate in percent of the second cash discount.
  - `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
  - `sourceTransactionId` (string (uuid)): Document this one was made from.
  - `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
  - `taxTotal` (number, read-only): Tax total, computed from the lines.
  - `tenantName` (string, read-only): Name of the tenant.
  - `transactionNumber` (string): Assigned with the type's prefix when empty on create.
  - `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
  - `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
  - `updatedAt` (string (date-time), read-only): When the transaction was last changed.
  - `validUntil` (string (date-time)): Offers only.
  - `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).

Example 200 answer:

```json
{
  "cancelledPurchaseOrders": [
    {
      "dropShip": false,
      "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d07",
      "poNumber": "BE-2026-0067",
      "status": "cancelled",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "supplierName": "Nordlicht IT-Distribution GmbH"
    }
  ],
  "flaggedCartLines": 1,
  "openPurchaseOrders": [],
  "order": {
    "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
    "currency": "EUR",
    "documentDate": "2026-11-12T00:00:00Z",
    "grossTotal": 2673.93,
    "id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e06",
    "netTotal": 2247,
    "recipientCompany": "Donau Maschinenbau AG",
    "status": "cancelled",
    "taxTotal": 426.93,
    "transactionNumber": "AB-2026-0145",
    "transactionType": "ORDER",
    "updatedAt": "2026-11-19T15:02:00Z",
    "version": 1
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/order-confirmations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/cancel' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Stock

## List stock levels (tenant:stock:read)

`GET /api/trade/v1/stock`

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

Stock of the tenant's default warehouse per article: on hand (sum of the movements), reserved (open order
quantity of the newest order revisions, drop-ship orders excluded), on order (open purchase orders, drafts
included) and available (`onHand - reserved + onOrder`). Without `articleIds` every article that has a rule or
a movement is listed, sorted by article id; a requested article without any data is answered with a zero level.
Articles are identified by their masterdata product id. Stock may be negative: deliveries are never blocked by
stock.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `articleIds` | query | string |  | Comma-separated article ids; only these (also when they have no stock yet). |
| `belowMinimum` | query | boolean |  | Only articles with a rule whose available quantity is below the minimum. (default `false`) |

### Responses

- **200** Stock levels (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `items` (array of StockLevel)
  - `articleId` (string): Masterdata product id.
  - `available` (number): `onHand - reserved + onOrder`.
  - `belowMinimum` (boolean): The article has a rule and `available` is below `minStock`.
  - `onHand` (number): Sum of the movements; may be negative.
  - `onOrder` (number): Open quantity of purchase orders (drafts included).
  - `reserved` (number): Open quantity of orders.
  - `rule` (null | object): The minimum-stock rule, null without one.
  - `warehouseId` (string): Warehouse code; empty before the first booking.
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d03",
      "available": 2,
      "belowMinimum": true,
      "onHand": 6,
      "onOrder": 0,
      "reserved": 4,
      "rule": {
        "minStock": 3,
        "reorderQty": 5
      },
      "warehouseId": "HAUPT"
    },
    {
      "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "available": 128,
      "belowMinimum": false,
      "onHand": 128,
      "onOrder": 0,
      "reserved": 0,
      "rule": {
        "maxStock": 200,
        "minStock": 50
      },
      "warehouseId": "HAUPT"
    }
  ],
  "total": 2
}
```

### Example request

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

## List the stock movements of an article (tenant:stock:read)

`GET /api/trade/v1/stock/{articleId}/movements`

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

The append-only movement history of the article, newest first.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | Page size; at most 500. (default `50`; max 500) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |
| `articleId` | path | string | yes | Masterdata product id of the article. |

### Responses

- **200** A page of movements, newest first (creation time, then id), and the number of all of them (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `items` (array of StockMovement, required)
  - `actor` (object): Who booked the movement.
    - `kind` (string): `user`, `service`, `system`, `workflow` or `public`.
    - `name` (string): Display name of the actor.
    - `ref` (string): The lower-case e-mail of a person, the instance id of a workflow.
  - `articleId` (string): Masterdata article.
  - `createdAt` (string (date-time)): When the movement was booked.
  - `id` (string (uuid)): Id of the movement.
  - `kind` (string): `return`: goods a customer returned with a credit note, booked back in when it is issued. (one of `goods_receipt`, `delivery`, `correction`, `count`, `reversal`, `return`)
  - `quantity` (number): Signed: receipts positive, deliveries negative.
  - `reason` (string): Reason of a correction or count.
  - `serials` (array of string): Serial numbers moved.
  - `sourceNumber` (string): Number of the source document.
  - `sourceTransactionId` (string (uuid)): The document the movement comes from (not for corrections and counts).
  - `warehouseId` (string): Warehouse of the movement.
- `total` (integer, required)
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "actor": {
        "kind": "user",
        "name": "David Richter",
        "ref": "david.richter@muster-it.example"
      },
      "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "createdAt": "2026-11-18T14:20:00Z",
      "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d03",
      "kind": "correction",
      "quantity": -2,
      "reason": "Bruch im Lager",
      "serials": [],
      "warehouseId": "HAUPT"
    },
    {
      "actor": {
        "kind": "user",
        "name": "David Richter",
        "ref": "david.richter@muster-it.example"
      },
      "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "createdAt": "2026-11-17T07:45:00Z",
      "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d02",
      "kind": "delivery",
      "quantity": -20,
      "serials": [],
      "sourceNumber": "LS-2026-0211",
      "sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
      "warehouseId": "HAUPT"
    },
    {
      "actor": {
        "kind": "user",
        "name": "David Richter",
        "ref": "david.richter@muster-it.example"
      },
      "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
      "createdAt": "2026-10-08T09:30:00Z",
      "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d01",
      "kind": "goods_receipt",
      "quantity": 150,
      "serials": [],
      "sourceNumber": "WE-2026-00037",
      "sourceTransactionId": "3d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f37",
      "warehouseId": "HAUPT"
    }
  ],
  "total": 3
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/stock/string/movements' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Set the minimum-stock rule of an article (tenant:stock:write)

`PUT /api/trade/v1/stock/{articleId}/rule`

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

Creates or replaces the rule. At most one of `reorderQty` (fixed batch) and `maxStock` (order up to) may be
set, and `maxStock` must not be below `minStock`. Only the default warehouse exists; another `warehouseId` is
answered `422`. An article that is already below its new minimum raises `trade.stock.below_minimum` at once.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `articleId` | path | string | yes | Masterdata product id of the article. |

### Request body

`application/json` (required)

- `minStock` (number, required): Minimum stock.
- `articleId` (string, read-only): From the path.
- `maxStock` (number, nullable): Order up to this quantity. Excludes `reorderQty`; not below `minStock`.
- `reorderQty` (number, nullable): Fixed batch to reorder. Excludes `maxStock`.
- `warehouseId` (string): Warehouse code; empty or the default warehouse (`HAUPT`).

Example:

```json
{
  "minStock": 5,
  "reorderQty": 20
}
```

### Responses

- **200** The stored rule (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 200 answer:

- `minStock` (number, required): Minimum stock.
- `articleId` (string, read-only): From the path.
- `maxStock` (number, nullable): Order up to this quantity. Excludes `reorderQty`; not below `minStock`.
- `reorderQty` (number, nullable): Fixed batch to reorder. Excludes `maxStock`.
- `warehouseId` (string): Warehouse code; empty or the default warehouse (`HAUPT`).

Example 200 answer:

```json
{
  "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
  "maxStock": 200,
  "minStock": 50,
  "reorderQty": null,
  "warehouseId": "HAUPT"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/stock/string/rule' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"minStock":5,"reorderQty":20}'
```

## Remove the minimum-stock rule of an article (tenant:stock:write)

`DELETE /api/trade/v1/stock/{articleId}/rule`

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

Removes the rule; the article no longer counts as below its minimum. A missing rule is not an error.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `warehouseId` | query | string |  | Only the default warehouse exists; another value is answered `422`. |
| `articleId` | path | string | yes | Masterdata product id of the article. |

### Responses

- **204** Removed
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/trade/v1/stock/string/rule' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Book a stock correction (tenant:stock:write)

`POST /api/trade/v1/stock/{articleId}/corrections`

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

Books a signed correction movement. The reason is required (`422` without). Each request books a new movement.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `articleId` | path | string | yes | Masterdata product id of the article. |

### Request body

`application/json` (required)

- `quantity` (number, required): Signed quantity to add to the stock.
- `reason` (string, required): Required.
- `warehouseId` (string): Empty or the default warehouse.

Example:

```json
{
  "quantity": -2,
  "reason": "Bruch im Lager"
}
```

### Responses

- **201** The booked movement (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 201 answer:

- `actor` (object): Who booked the movement.
  - `kind` (string): `user`, `service`, `system`, `workflow` or `public`.
  - `name` (string): Display name of the actor.
  - `ref` (string): The lower-case e-mail of a person, the instance id of a workflow.
- `articleId` (string): Masterdata article.
- `createdAt` (string (date-time)): When the movement was booked.
- `id` (string (uuid)): Id of the movement.
- `kind` (string): `return`: goods a customer returned with a credit note, booked back in when it is issued. (one of `goods_receipt`, `delivery`, `correction`, `count`, `reversal`, `return`)
- `quantity` (number): Signed: receipts positive, deliveries negative.
- `reason` (string): Reason of a correction or count.
- `serials` (array of string): Serial numbers moved.
- `sourceNumber` (string): Number of the source document.
- `sourceTransactionId` (string (uuid)): The document the movement comes from (not for corrections and counts).
- `warehouseId` (string): Warehouse of the movement.

Example 201 answer:

```json
{
  "actor": {
    "kind": "user",
    "name": "David Richter",
    "ref": "david.richter@muster-it.example"
  },
  "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
  "createdAt": "2026-11-18T14:20:00Z",
  "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d03",
  "kind": "correction",
  "quantity": -2,
  "reason": "Bruch im Lager",
  "serials": [],
  "warehouseId": "HAUPT"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/stock/string/corrections' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"quantity":-2,"reason":"Bruch im Lager"}'
```

## Book an inventory count (tenant:stock:write)

`POST /api/trade/v1/stock/{articleId}/counts`

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

Sets the on-hand stock to the counted quantity by booking the difference to the committed stock (a receipt that
arrives at the same time is not lost). The reason is required (`422` without). When the count equals the stock
nothing is booked and the answer is `204`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `articleId` | path | string | yes | Masterdata product id of the article. |

### Request body

`application/json` (required)

- `counted` (number, required): The counted quantity; the stock is set to it.
- `reason` (string, required): Required.
- `warehouseId` (string): Empty or the default warehouse.

Example:

```json
{
  "counted": 12,
  "reason": "Jahresinventur"
}
```

### Responses

- **201** The booked difference (`application/json`)
- **204** The count equals the stock; nothing booked
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 201 answer:

- `actor` (object): Who booked the movement.
  - `kind` (string): `user`, `service`, `system`, `workflow` or `public`.
  - `name` (string): Display name of the actor.
  - `ref` (string): The lower-case e-mail of a person, the instance id of a workflow.
- `articleId` (string): Masterdata article.
- `createdAt` (string (date-time)): When the movement was booked.
- `id` (string (uuid)): Id of the movement.
- `kind` (string): `return`: goods a customer returned with a credit note, booked back in when it is issued. (one of `goods_receipt`, `delivery`, `correction`, `count`, `reversal`, `return`)
- `quantity` (number): Signed: receipts positive, deliveries negative.
- `reason` (string): Reason of a correction or count.
- `serials` (array of string): Serial numbers moved.
- `sourceNumber` (string): Number of the source document.
- `sourceTransactionId` (string (uuid)): The document the movement comes from (not for corrections and counts).
- `warehouseId` (string): Warehouse of the movement.

Example 201 answer:

```json
{
  "actor": {
    "kind": "user",
    "name": "David Richter",
    "ref": "david.richter@muster-it.example"
  },
  "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
  "createdAt": "2026-11-19T16:00:00Z",
  "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d04",
  "kind": "count",
  "quantity": 2,
  "reason": "Jahresinventur",
  "serials": [],
  "warehouseId": "HAUPT"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/stock/string/counts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"counted":12,"reason":"Jahresinventur"}'
```

# Inbound delivery notes

## List supplier delivery notes (tenant:trade:purchasing:read)

`GET /api/trade/v1/inbound-delivery-notes`

Module: Trade · operationId: `listInboundDeliveryNotes` · Tag: Inbound delivery notes · Auth: access token (`Authorization: Bearer <accessToken>`)

Newest first (creation time, then id), without lines, reading and OCR text; pages by keyset (`nextCursor`), `total` counts all matches.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string |  | One status or a comma-separated list (case-insensitive), e.g. `MATCHED,DISCREPANCY`. |
| `search` | query | string |  | Substring of the internal number, the supplier's delivery note number, the supplier name or the purchase order number. |
| `limit` | query | integer |  | 1–200 (else `400 invalid`). (default `50`; max 200) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** Delivery notes (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of InboundDeliveryNote, required): The delivery notes of the page.
  - `autoPost` (AutoPostDecision): Verdict of the automatic goods receipt on an inbound delivery note, stored whenever the mode is not `off`.
    - `eligible` (boolean): Every condition holds: matched without discrepancy, every line on the order and delivered completely, from EGIS (per shipment) or read with enough confidence and covering every open line of the order (`match.uncoveredPoPositions` empty), order not chosen by a person.
    - `evaluatedAt` (string (date-time)): When the decision was evaluated.
    - `mode` (string): Mode of the automatic goods receipt when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
    - `posted` (boolean): The system posted the goods receipt (mode `on`).
    - `reasons` (array of string): Each failed condition (German text).
    - `rule` (string): The rule an automatic post applied (German text), also in the protocol entry of the posting.
  - `createdAt` (string (date-time)): When the delivery note was created.
  - `deliveryDate` (string (date)): Delivery date.
  - `deliveryNoteNumber` (string): The supplier's number.
  - `dmsDocumentId` (string (uuid)): Missing for delivery notes EGIS reported (`source` egis).
  - `error` (string): Why processing failed.
  - `externalReference` (string): `egis:<EGIS order number>:<EGIS delivery note id>` for EGIS delivery notes (one per order the note covers).
  - `extraction` (object): What the AI read; never changed afterwards. Not in lists.
    - `confidence` (number): Confidence of the extraction (0–1).
    - `customerNumber` (string): Our customer number at the supplier.
    - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
    - `deliveryNoteNumber` (string): The supplier's delivery note number.
    - `lines` (array of InboundDeliveryNoteLine): Lines read from the document.
    - `model` (string): AI model that read the document.
    - `notes` (string): Notes of the extraction.
    - `orderNumbers` (array of string): Order numbers stated on the delivery note.
    - `supplier` (Party)
      - `address` (string): Single-line address (e-invoice).
      - `city` (string): City.
      - `country` (string): Country.
      - `iban` (string): IBAN.
      - `name` (string): Name.
      - `street` (string): Street and house number.
      - `taxNumber` (string): Tax number.
      - `vatId` (string): VAT identification number.
      - `zip` (string): Postal code.
  - `fullText` (string): OCR text; only in the single read.
  - `id` (string (uuid)): Id of the delivery note.
  - `lines` (array of InboundDeliveryNoteLine): Empty in lists.
    - `articleNumber` (string): The masterdata article the line was assigned to.
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `mpn` (string): Manufacturer part number.
    - `orderNumber` (string): Purchase order number printed on the line.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Delivered quantity.
    - `serialNumbers` (array of string): Serial numbers.
    - `unit` (string): Unit of measure.
    - `vendorArticleNo` (string): The supplier's article number as read.
  - `match` (DeliveryCheck): The check of the delivered lines against the open quantities (ordered − received) of the purchase order.
    - `discrepancies` (array of LockReason): `MINDERLIEFERUNG` (partial delivery, not blocking), `MEHRLIEFERUNG` (more than open), `UNBEKANNTE_POSITION`, `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`.
    - `evaluatedAt` (string (date-time)): When the check ran.
    - `lines` (array of object): Result per delivery note line.
      - `deliveredQty` (number): Quantity delivered.
      - `description` (string): Description of the line.
      - `openQty` (number): Ordered minus received before this note.
      - `orderedQty` (number): Quantity ordered.
      - `poLineId` (string (uuid)): Empty when the line is not on the order.
      - `poPosition` (integer): Position on the purchase order.
      - `position` (integer): Position number of the line.
      - `result` (string): Result of the line. (one of `OK`, `SHORT`, `OVER`, `UNKNOWN_POSITION`)
      - `variance` (number): Delivered minus open (negative: partial delivery).
    - `status` (string): Outcome of the check against the purchase order. (one of `matched`, `discrepancy`)
    - `uncoveredPoPositions` (array of integer): Positions of order lines with an open quantity the note does not deliver at all (a partial delivery of the order; no discrepancy).
  - `orderReference` (string): Order numbers named on the note.
  - `posting` (object): The goods receipt posted from the delivery note.
    - `goodsReceiptId` (string (uuid)): Id of the goods receipt.
    - `grNumber` (string): Number of the goods receipt.
    - `postedAt` (string (date-time)): When it was posted.
    - `postedBy` (string): Who posted it.
  - `purchaseOrderFixed` (boolean): A person chose the purchase order.
  - `purchaseOrderId` (string (uuid)): Purchase order the delivery note was assigned to.
  - `purchaseOrderNumber` (string): Number of the purchase order.
  - `source` (string): `egis` for a delivery note EGIS reported for an order sent through it (structured, with serial numbers; no document, no AI reading). (one of `egis`)
  - `status` (InboundDeliveryNoteStatus): `RECEIVED` waits for the text, `EXTRACTED` is read, `MATCHED` / `DISCREPANCY` checked against the purchase order (findings in `match.discrepancies`), `POSTED` booked as goods receipt, `FAILED` could not be read (`error`, retry with reprocess), `REJECTED` discarded by a person. (one of `RECEIVED`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `POSTED`, `REJECTED`, `FAILED`)
  - `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
  - `supplierAssignment` (object): How the supplier was found.
    - `confidence` (number): Confidence of the assignment (0–1).
    - `evidence` (string): What the assignment is based on.
    - `method` (string): How the supplier was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`.
  - `supplierName` (string): Name of the supplier.
  - `transactionNumber` (string): Internal number of the delivery note (e.g. `LE-2026-00001`).
  - `updatedAt` (string (date-time)): When the delivery note was last changed.
- `total` (integer, required): Number of entries of the whole list.
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-18T10:01:00Z",
      "deliveryDate": "2026-11-18",
      "deliveryNoteNumber": "LS-778812",
      "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b11",
      "id": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a01",
      "lines": [],
      "purchaseOrderFixed": false,
      "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
      "purchaseOrderNumber": "BE-2026-00068",
      "status": "MATCHED",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
      "supplierName": "Kabelwerk Süd GmbH",
      "transactionNumber": "LE-2026-00012",
      "updatedAt": "2026-11-18T10:02:30Z"
    },
    {
      "createdAt": "2026-11-12T16:00:00Z",
      "deliveryDate": "2026-11-12",
      "deliveryNoteNumber": "503508",
      "externalReference": "egis:0000731990:503508",
      "id": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a21",
      "lines": [],
      "purchaseOrderFixed": true,
      "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d69",
      "purchaseOrderNumber": "BE-2026-00069",
      "source": "egis",
      "status": "POSTED",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "supplierName": "Nordlicht IT-Distribution GmbH",
      "transactionNumber": "LE-2026-00011",
      "updatedAt": "2026-11-12T16:00:05Z"
    }
  ],
  "total": 12
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/inbound-delivery-notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Process a DMS document as supplier delivery note (tenant:trade:purchasing:write)

`POST /api/trade/v1/inbound-delivery-notes`

Module: Trade · operationId: `createInboundDeliveryNote` · Tag: Inbound delivery notes · Auth: access token (`Authorization: Bearer <accessToken>`)

Registers an existing DMS document as delivery note and reads it when its text extraction is done
(the request waits for the AI reading). Idempotent per document: a document that already has a
delivery note beyond `RECEIVED` answers it. A document the inbound invoice pipeline holds but has
not read as invoice yet (or rejected as no invoice) becomes the delivery note; one it read as
invoice answers `409`. Documents normally arrive automatically: DMS documents whose type routes to
`trade.delivery_note`, and Eingangsbelege the inbound invoice pipeline classifies as delivery note
(UNTDID 1001 `270`).

### Request body

`application/json` (required)

- `dmsDocumentId` (string (uuid), required)

Example:

```json
{
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b12"
}
```

### Responses

- **201** The delivery note (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **409** The current state does not allow the action (`code` `invalid_state` or `blocked`). (`application/json`)
- **422** The DMS document does not exist. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 201 answer:

- `autoPost` (AutoPostDecision): Verdict of the automatic goods receipt on an inbound delivery note, stored whenever the mode is not `off`.
  - `eligible` (boolean): Every condition holds: matched without discrepancy, every line on the order and delivered completely, from EGIS (per shipment) or read with enough confidence and covering every open line of the order (`match.uncoveredPoPositions` empty), order not chosen by a person.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic goods receipt when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `posted` (boolean): The system posted the goods receipt (mode `on`).
  - `reasons` (array of string): Each failed condition (German text).
  - `rule` (string): The rule an automatic post applied (German text), also in the protocol entry of the posting.
- `createdAt` (string (date-time)): When the delivery note was created.
- `deliveryDate` (string (date)): Delivery date.
- `deliveryNoteNumber` (string): The supplier's number.
- `dmsDocumentId` (string (uuid)): Missing for delivery notes EGIS reported (`source` egis).
- `error` (string): Why processing failed.
- `externalReference` (string): `egis:<EGIS order number>:<EGIS delivery note id>` for EGIS delivery notes (one per order the note covers).
- `extraction` (object): What the AI read; never changed afterwards. Not in lists.
  - `confidence` (number): Confidence of the extraction (0–1).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): The supplier's delivery note number.
  - `lines` (array of InboundDeliveryNoteLine): Lines read from the document.
    - `articleNumber` (string): The masterdata article the line was assigned to.
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `mpn` (string): Manufacturer part number.
    - `orderNumber` (string): Purchase order number printed on the line.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Delivered quantity.
    - `serialNumbers` (array of string): Serial numbers.
    - `unit` (string): Unit of measure.
    - `vendorArticleNo` (string): The supplier's article number as read.
  - `model` (string): AI model that read the document.
  - `notes` (string): Notes of the extraction.
  - `orderNumbers` (array of string): Order numbers stated on the delivery note.
  - `supplier` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text; only in the single read.
- `id` (string (uuid)): Id of the delivery note.
- `lines` (array of InboundDeliveryNoteLine): Empty in lists.
  - `articleNumber` (string): The masterdata article the line was assigned to.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `mpn` (string): Manufacturer part number.
  - `orderNumber` (string): Purchase order number printed on the line.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Delivered quantity.
  - `serialNumbers` (array of string): Serial numbers.
  - `unit` (string): Unit of measure.
  - `vendorArticleNo` (string): The supplier's article number as read.
- `match` (DeliveryCheck): The check of the delivered lines against the open quantities (ordered − received) of the purchase order.
  - `discrepancies` (array of LockReason): `MINDERLIEFERUNG` (partial delivery, not blocking), `MEHRLIEFERUNG` (more than open), `UNBEKANNTE_POSITION`, `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `evaluatedAt` (string (date-time)): When the check ran.
  - `lines` (array of object): Result per delivery note line.
    - `deliveredQty` (number): Quantity delivered.
    - `description` (string): Description of the line.
    - `openQty` (number): Ordered minus received before this note.
    - `orderedQty` (number): Quantity ordered.
    - `poLineId` (string (uuid)): Empty when the line is not on the order.
    - `poPosition` (integer): Position on the purchase order.
    - `position` (integer): Position number of the line.
    - `result` (string): Result of the line. (one of `OK`, `SHORT`, `OVER`, `UNKNOWN_POSITION`)
    - `variance` (number): Delivered minus open (negative: partial delivery).
  - `status` (string): Outcome of the check against the purchase order. (one of `matched`, `discrepancy`)
  - `uncoveredPoPositions` (array of integer): Positions of order lines with an open quantity the note does not deliver at all (a partial delivery of the order; no discrepancy).
- `orderReference` (string): Order numbers named on the note.
- `posting` (object): The goods receipt posted from the delivery note.
  - `goodsReceiptId` (string (uuid)): Id of the goods receipt.
  - `grNumber` (string): Number of the goods receipt.
  - `postedAt` (string (date-time)): When it was posted.
  - `postedBy` (string): Who posted it.
- `purchaseOrderFixed` (boolean): A person chose the purchase order.
- `purchaseOrderId` (string (uuid)): Purchase order the delivery note was assigned to.
- `purchaseOrderNumber` (string): Number of the purchase order.
- `source` (string): `egis` for a delivery note EGIS reported for an order sent through it (structured, with serial numbers; no document, no AI reading). (one of `egis`)
- `status` (InboundDeliveryNoteStatus): `RECEIVED` waits for the text, `EXTRACTED` is read, `MATCHED` / `DISCREPANCY` checked against the purchase order (findings in `match.discrepancies`), `POSTED` booked as goods receipt, `FAILED` could not be read (`error`, retry with reprocess), `REJECTED` discarded by a person. (one of `RECEIVED`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `POSTED`, `REJECTED`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierAssignment` (object): How the supplier was found.
  - `confidence` (number): Confidence of the assignment (0–1).
  - `evidence` (string): What the assignment is based on.
  - `method` (string): How the supplier was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`.
- `supplierName` (string): Name of the supplier.
- `transactionNumber` (string): Internal number of the delivery note (e.g. `LE-2026-00001`).
- `updatedAt` (string (date-time)): When the delivery note was last changed.

Example 201 answer:

```json
{
  "createdAt": "2026-11-19T09:20:00Z",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b12",
  "id": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a02",
  "lines": [],
  "status": "RECEIVED",
  "transactionNumber": "LE-2026-00013",
  "updatedAt": "2026-11-19T09:20:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-delivery-notes' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"dmsDocumentId":"9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b12"}'
```

## Get a supplier delivery note (tenant:trade:purchasing:read)

`GET /api/trade/v1/inbound-delivery-notes/{id}`

Module: Trade · operationId: `getInboundDeliveryNote` · Tag: Inbound delivery notes · Auth: access token (`Authorization: Bearer <accessToken>`)

With lines, the reading (`extraction`) and the check against the purchase order (`match`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The delivery note (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `autoPost` (AutoPostDecision): Verdict of the automatic goods receipt on an inbound delivery note, stored whenever the mode is not `off`.
  - `eligible` (boolean): Every condition holds: matched without discrepancy, every line on the order and delivered completely, from EGIS (per shipment) or read with enough confidence and covering every open line of the order (`match.uncoveredPoPositions` empty), order not chosen by a person.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic goods receipt when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `posted` (boolean): The system posted the goods receipt (mode `on`).
  - `reasons` (array of string): Each failed condition (German text).
  - `rule` (string): The rule an automatic post applied (German text), also in the protocol entry of the posting.
- `createdAt` (string (date-time)): When the delivery note was created.
- `deliveryDate` (string (date)): Delivery date.
- `deliveryNoteNumber` (string): The supplier's number.
- `dmsDocumentId` (string (uuid)): Missing for delivery notes EGIS reported (`source` egis).
- `error` (string): Why processing failed.
- `externalReference` (string): `egis:<EGIS order number>:<EGIS delivery note id>` for EGIS delivery notes (one per order the note covers).
- `extraction` (object): What the AI read; never changed afterwards. Not in lists.
  - `confidence` (number): Confidence of the extraction (0–1).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): The supplier's delivery note number.
  - `lines` (array of InboundDeliveryNoteLine): Lines read from the document.
    - `articleNumber` (string): The masterdata article the line was assigned to.
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `mpn` (string): Manufacturer part number.
    - `orderNumber` (string): Purchase order number printed on the line.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Delivered quantity.
    - `serialNumbers` (array of string): Serial numbers.
    - `unit` (string): Unit of measure.
    - `vendorArticleNo` (string): The supplier's article number as read.
  - `model` (string): AI model that read the document.
  - `notes` (string): Notes of the extraction.
  - `orderNumbers` (array of string): Order numbers stated on the delivery note.
  - `supplier` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text; only in the single read.
- `id` (string (uuid)): Id of the delivery note.
- `lines` (array of InboundDeliveryNoteLine): Empty in lists.
  - `articleNumber` (string): The masterdata article the line was assigned to.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `mpn` (string): Manufacturer part number.
  - `orderNumber` (string): Purchase order number printed on the line.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Delivered quantity.
  - `serialNumbers` (array of string): Serial numbers.
  - `unit` (string): Unit of measure.
  - `vendorArticleNo` (string): The supplier's article number as read.
- `match` (DeliveryCheck): The check of the delivered lines against the open quantities (ordered − received) of the purchase order.
  - `discrepancies` (array of LockReason): `MINDERLIEFERUNG` (partial delivery, not blocking), `MEHRLIEFERUNG` (more than open), `UNBEKANNTE_POSITION`, `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `evaluatedAt` (string (date-time)): When the check ran.
  - `lines` (array of object): Result per delivery note line.
    - `deliveredQty` (number): Quantity delivered.
    - `description` (string): Description of the line.
    - `openQty` (number): Ordered minus received before this note.
    - `orderedQty` (number): Quantity ordered.
    - `poLineId` (string (uuid)): Empty when the line is not on the order.
    - `poPosition` (integer): Position on the purchase order.
    - `position` (integer): Position number of the line.
    - `result` (string): Result of the line. (one of `OK`, `SHORT`, `OVER`, `UNKNOWN_POSITION`)
    - `variance` (number): Delivered minus open (negative: partial delivery).
  - `status` (string): Outcome of the check against the purchase order. (one of `matched`, `discrepancy`)
  - `uncoveredPoPositions` (array of integer): Positions of order lines with an open quantity the note does not deliver at all (a partial delivery of the order; no discrepancy).
- `orderReference` (string): Order numbers named on the note.
- `posting` (object): The goods receipt posted from the delivery note.
  - `goodsReceiptId` (string (uuid)): Id of the goods receipt.
  - `grNumber` (string): Number of the goods receipt.
  - `postedAt` (string (date-time)): When it was posted.
  - `postedBy` (string): Who posted it.
- `purchaseOrderFixed` (boolean): A person chose the purchase order.
- `purchaseOrderId` (string (uuid)): Purchase order the delivery note was assigned to.
- `purchaseOrderNumber` (string): Number of the purchase order.
- `source` (string): `egis` for a delivery note EGIS reported for an order sent through it (structured, with serial numbers; no document, no AI reading). (one of `egis`)
- `status` (InboundDeliveryNoteStatus): `RECEIVED` waits for the text, `EXTRACTED` is read, `MATCHED` / `DISCREPANCY` checked against the purchase order (findings in `match.discrepancies`), `POSTED` booked as goods receipt, `FAILED` could not be read (`error`, retry with reprocess), `REJECTED` discarded by a person. (one of `RECEIVED`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `POSTED`, `REJECTED`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierAssignment` (object): How the supplier was found.
  - `confidence` (number): Confidence of the assignment (0–1).
  - `evidence` (string): What the assignment is based on.
  - `method` (string): How the supplier was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`.
- `supplierName` (string): Name of the supplier.
- `transactionNumber` (string): Internal number of the delivery note (e.g. `LE-2026-00001`).
- `updatedAt` (string (date-time)): When the delivery note was last changed.

Example 200 answer:

```json
{
  "autoPost": {
    "eligible": true,
    "evaluatedAt": "2026-11-18T10:02:30Z",
    "mode": "dryRun",
    "posted": false,
    "reasons": [],
    "rule": "Lieferschein deckt die Bestellung BE-2026-00068 vollständig (KI-Konfidenz 0,96 ≥ 0,90)."
  },
  "createdAt": "2026-11-18T10:01:00Z",
  "deliveryDate": "2026-11-18",
  "deliveryNoteNumber": "LS-778812",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b11",
  "extraction": {
    "confidence": 0.96,
    "customerNumber": "204711",
    "deliveryDate": "2026-11-18",
    "deliveryNoteNumber": "LS-778812",
    "lines": [
      {
        "articleNumber": "NW-2004",
        "description": "Netzwerkschrank 19 Zoll 12 HE",
        "orderNumber": "BE-2026-00068",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
        "quantity": 1,
        "serialNumbers": [
          "RK12-26-0457"
        ],
        "unit": "STK",
        "vendorArticleNo": "KW-RACK12HE"
      },
      {
        "articleNumber": "NW-2005",
        "description": "Verlegekabel Cat.7 Simplex, 100 m",
        "orderNumber": "BE-2026-00068",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
        "quantity": 3,
        "serialNumbers": [],
        "unit": "PAK",
        "vendorArticleNo": "KW-CAT7-100"
      }
    ],
    "model": "medium",
    "orderNumbers": [
      "BE-2026-00068"
    ],
    "supplier": {
      "city": "Augsburg",
      "country": "DE",
      "name": "Kabelwerk Süd GmbH",
      "street": "Gewerbering 7",
      "vatId": "DE701000002",
      "zip": "86167"
    }
  },
  "id": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a01",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "orderNumber": "BE-2026-00068",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "quantity": 1,
      "serialNumbers": [
        "RK12-26-0457"
      ],
      "unit": "STK",
      "vendorArticleNo": "KW-RACK12HE"
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "orderNumber": "BE-2026-00068",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "quantity": 3,
      "serialNumbers": [],
      "unit": "PAK",
      "vendorArticleNo": "KW-CAT7-100"
    }
  ],
  "match": {
    "discrepancies": [],
    "evaluatedAt": "2026-11-18T10:02:30Z",
    "lines": [
      {
        "deliveredQty": 1,
        "description": "Netzwerkschrank 19 Zoll 12 HE",
        "openQty": 1,
        "orderedQty": 1,
        "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
        "poPosition": 1,
        "position": 1,
        "result": "OK",
        "variance": 0
      },
      {
        "deliveredQty": 3,
        "description": "Verlegekabel Cat.7 Simplex, 100 m",
        "openQty": 3,
        "orderedQty": 3,
        "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
        "poPosition": 2,
        "position": 2,
        "result": "OK",
        "variance": 0
      }
    ],
    "status": "matched",
    "uncoveredPoPositions": []
  },
  "orderReference": "BE-2026-00068",
  "purchaseOrderFixed": false,
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "purchaseOrderNumber": "BE-2026-00068",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierAssignment": {
    "confidence": 1,
    "evidence": "USt-IdNr. DE701000002",
    "method": "exact_vat"
  },
  "supplierName": "Kabelwerk Süd GmbH",
  "transactionNumber": "LE-2026-00012",
  "updatedAt": "2026-11-18T10:02:30Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/inbound-delivery-notes/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Assign a delivery note to a purchase order (tenant:trade:purchasing:write)

`PATCH /api/trade/v1/inbound-delivery-notes/{id}`

Module: Trade · operationId: `updateInboundDeliveryNote` · Tag: Inbound delivery notes · Auth: access token (`Authorization: Bearer <accessToken>`)

Sets the purchase order a person chose (kept when the note is read again) and checks the lines
against it; without `purchaseOrderId` the order is looked up again from the note. Only in
`EXTRACTED`, `MATCHED` and `DISCREPANCY`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `purchaseOrderId` (string (uuid), nullable)

Example:

```json
{
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68"
}
```

### Responses

- **200** The delivery note (`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 current state does not allow the action (`code` `invalid_state` or `blocked`). (`application/json`)
- **422** The purchase order does not exist. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `autoPost` (AutoPostDecision): Verdict of the automatic goods receipt on an inbound delivery note, stored whenever the mode is not `off`.
  - `eligible` (boolean): Every condition holds: matched without discrepancy, every line on the order and delivered completely, from EGIS (per shipment) or read with enough confidence and covering every open line of the order (`match.uncoveredPoPositions` empty), order not chosen by a person.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic goods receipt when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `posted` (boolean): The system posted the goods receipt (mode `on`).
  - `reasons` (array of string): Each failed condition (German text).
  - `rule` (string): The rule an automatic post applied (German text), also in the protocol entry of the posting.
- `createdAt` (string (date-time)): When the delivery note was created.
- `deliveryDate` (string (date)): Delivery date.
- `deliveryNoteNumber` (string): The supplier's number.
- `dmsDocumentId` (string (uuid)): Missing for delivery notes EGIS reported (`source` egis).
- `error` (string): Why processing failed.
- `externalReference` (string): `egis:<EGIS order number>:<EGIS delivery note id>` for EGIS delivery notes (one per order the note covers).
- `extraction` (object): What the AI read; never changed afterwards. Not in lists.
  - `confidence` (number): Confidence of the extraction (0–1).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): The supplier's delivery note number.
  - `lines` (array of InboundDeliveryNoteLine): Lines read from the document.
    - `articleNumber` (string): The masterdata article the line was assigned to.
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `mpn` (string): Manufacturer part number.
    - `orderNumber` (string): Purchase order number printed on the line.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Delivered quantity.
    - `serialNumbers` (array of string): Serial numbers.
    - `unit` (string): Unit of measure.
    - `vendorArticleNo` (string): The supplier's article number as read.
  - `model` (string): AI model that read the document.
  - `notes` (string): Notes of the extraction.
  - `orderNumbers` (array of string): Order numbers stated on the delivery note.
  - `supplier` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text; only in the single read.
- `id` (string (uuid)): Id of the delivery note.
- `lines` (array of InboundDeliveryNoteLine): Empty in lists.
  - `articleNumber` (string): The masterdata article the line was assigned to.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `mpn` (string): Manufacturer part number.
  - `orderNumber` (string): Purchase order number printed on the line.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Delivered quantity.
  - `serialNumbers` (array of string): Serial numbers.
  - `unit` (string): Unit of measure.
  - `vendorArticleNo` (string): The supplier's article number as read.
- `match` (DeliveryCheck): The check of the delivered lines against the open quantities (ordered − received) of the purchase order.
  - `discrepancies` (array of LockReason): `MINDERLIEFERUNG` (partial delivery, not blocking), `MEHRLIEFERUNG` (more than open), `UNBEKANNTE_POSITION`, `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `evaluatedAt` (string (date-time)): When the check ran.
  - `lines` (array of object): Result per delivery note line.
    - `deliveredQty` (number): Quantity delivered.
    - `description` (string): Description of the line.
    - `openQty` (number): Ordered minus received before this note.
    - `orderedQty` (number): Quantity ordered.
    - `poLineId` (string (uuid)): Empty when the line is not on the order.
    - `poPosition` (integer): Position on the purchase order.
    - `position` (integer): Position number of the line.
    - `result` (string): Result of the line. (one of `OK`, `SHORT`, `OVER`, `UNKNOWN_POSITION`)
    - `variance` (number): Delivered minus open (negative: partial delivery).
  - `status` (string): Outcome of the check against the purchase order. (one of `matched`, `discrepancy`)
  - `uncoveredPoPositions` (array of integer): Positions of order lines with an open quantity the note does not deliver at all (a partial delivery of the order; no discrepancy).
- `orderReference` (string): Order numbers named on the note.
- `posting` (object): The goods receipt posted from the delivery note.
  - `goodsReceiptId` (string (uuid)): Id of the goods receipt.
  - `grNumber` (string): Number of the goods receipt.
  - `postedAt` (string (date-time)): When it was posted.
  - `postedBy` (string): Who posted it.
- `purchaseOrderFixed` (boolean): A person chose the purchase order.
- `purchaseOrderId` (string (uuid)): Purchase order the delivery note was assigned to.
- `purchaseOrderNumber` (string): Number of the purchase order.
- `source` (string): `egis` for a delivery note EGIS reported for an order sent through it (structured, with serial numbers; no document, no AI reading). (one of `egis`)
- `status` (InboundDeliveryNoteStatus): `RECEIVED` waits for the text, `EXTRACTED` is read, `MATCHED` / `DISCREPANCY` checked against the purchase order (findings in `match.discrepancies`), `POSTED` booked as goods receipt, `FAILED` could not be read (`error`, retry with reprocess), `REJECTED` discarded by a person. (one of `RECEIVED`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `POSTED`, `REJECTED`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierAssignment` (object): How the supplier was found.
  - `confidence` (number): Confidence of the assignment (0–1).
  - `evidence` (string): What the assignment is based on.
  - `method` (string): How the supplier was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`.
- `supplierName` (string): Name of the supplier.
- `transactionNumber` (string): Internal number of the delivery note (e.g. `LE-2026-00001`).
- `updatedAt` (string (date-time)): When the delivery note was last changed.

Example 200 answer:

```json
{
  "autoPost": {
    "eligible": false,
    "evaluatedAt": "2026-11-18T10:05:00Z",
    "mode": "dryRun",
    "posted": false,
    "reasons": [
      "Die Bestellung wurde von einer Person gewählt."
    ]
  },
  "createdAt": "2026-11-18T10:01:00Z",
  "deliveryDate": "2026-11-18",
  "deliveryNoteNumber": "LS-778812",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b11",
  "extraction": {
    "confidence": 0.96,
    "customerNumber": "204711",
    "deliveryDate": "2026-11-18",
    "deliveryNoteNumber": "LS-778812",
    "lines": [
      {
        "articleNumber": "NW-2004",
        "description": "Netzwerkschrank 19 Zoll 12 HE",
        "orderNumber": "BE-2026-00068",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
        "quantity": 1,
        "serialNumbers": [
          "RK12-26-0457"
        ],
        "unit": "STK",
        "vendorArticleNo": "KW-RACK12HE"
      },
      {
        "articleNumber": "NW-2005",
        "description": "Verlegekabel Cat.7 Simplex, 100 m",
        "orderNumber": "BE-2026-00068",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
        "quantity": 3,
        "serialNumbers": [],
        "unit": "PAK",
        "vendorArticleNo": "KW-CAT7-100"
      }
    ],
    "model": "medium",
    "orderNumbers": [
      "BE-2026-00068"
    ],
    "supplier": {
      "city": "Augsburg",
      "country": "DE",
      "name": "Kabelwerk Süd GmbH",
      "street": "Gewerbering 7",
      "vatId": "DE701000002",
      "zip": "86167"
    }
  },
  "id": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a01",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "orderNumber": "BE-2026-00068",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "quantity": 1,
      "serialNumbers": [
        "RK12-26-0457"
      ],
      "unit": "STK",
      "vendorArticleNo": "KW-RACK12HE"
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "orderNumber": "BE-2026-00068",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "quantity": 3,
      "serialNumbers": [],
      "unit": "PAK",
      "vendorArticleNo": "KW-CAT7-100"
    }
  ],
  "match": {
    "discrepancies": [],
    "evaluatedAt": "2026-11-18T10:02:30Z",
    "lines": [
      {
        "deliveredQty": 1,
        "description": "Netzwerkschrank 19 Zoll 12 HE",
        "openQty": 1,
        "orderedQty": 1,
        "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
        "poPosition": 1,
        "position": 1,
        "result": "OK",
        "variance": 0
      },
      {
        "deliveredQty": 3,
        "description": "Verlegekabel Cat.7 Simplex, 100 m",
        "openQty": 3,
        "orderedQty": 3,
        "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
        "poPosition": 2,
        "position": 2,
        "result": "OK",
        "variance": 0
      }
    ],
    "status": "matched",
    "uncoveredPoPositions": []
  },
  "orderReference": "BE-2026-00068",
  "purchaseOrderFixed": true,
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "purchaseOrderNumber": "BE-2026-00068",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierAssignment": {
    "confidence": 1,
    "evidence": "USt-IdNr. DE701000002",
    "method": "exact_vat"
  },
  "supplierName": "Kabelwerk Süd GmbH",
  "transactionNumber": "LE-2026-00012",
  "updatedAt": "2026-11-18T10:05:00Z"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/trade/v1/inbound-delivery-notes/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"purchaseOrderId":"1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68"}'
```

## Download the delivery note document (tenant:trade:purchasing:read)

`GET /api/trade/v1/inbound-delivery-notes/{id}/document`

Module: Trade · operationId: `getInboundDeliveryNoteDocument` · Tag: Inbound delivery notes · Auth: access token (`Authorization: Bearer <accessToken>`)

Streams the DMS file of the delivery note with its `Content-Type`, `Content-Disposition` and `ETag`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The file (`application/octet-stream`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/inbound-delivery-notes/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/document' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Check a delivery note against its purchase order again (tenant:trade:purchasing:write)

`POST /api/trade/v1/inbound-delivery-notes/{id}/match`

Module: Trade · operationId: `matchInboundDeliveryNote` · Tag: Inbound delivery notes · Auth: access token (`Authorization: Bearer <accessToken>`)

Uses the current received quantities of the order (e.g. after a goods receipt entered by hand).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The delivery note (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** The current state does not allow the action (`code` `invalid_state` or `blocked`). (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `autoPost` (AutoPostDecision): Verdict of the automatic goods receipt on an inbound delivery note, stored whenever the mode is not `off`.
  - `eligible` (boolean): Every condition holds: matched without discrepancy, every line on the order and delivered completely, from EGIS (per shipment) or read with enough confidence and covering every open line of the order (`match.uncoveredPoPositions` empty), order not chosen by a person.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic goods receipt when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `posted` (boolean): The system posted the goods receipt (mode `on`).
  - `reasons` (array of string): Each failed condition (German text).
  - `rule` (string): The rule an automatic post applied (German text), also in the protocol entry of the posting.
- `createdAt` (string (date-time)): When the delivery note was created.
- `deliveryDate` (string (date)): Delivery date.
- `deliveryNoteNumber` (string): The supplier's number.
- `dmsDocumentId` (string (uuid)): Missing for delivery notes EGIS reported (`source` egis).
- `error` (string): Why processing failed.
- `externalReference` (string): `egis:<EGIS order number>:<EGIS delivery note id>` for EGIS delivery notes (one per order the note covers).
- `extraction` (object): What the AI read; never changed afterwards. Not in lists.
  - `confidence` (number): Confidence of the extraction (0–1).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): The supplier's delivery note number.
  - `lines` (array of InboundDeliveryNoteLine): Lines read from the document.
    - `articleNumber` (string): The masterdata article the line was assigned to.
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `mpn` (string): Manufacturer part number.
    - `orderNumber` (string): Purchase order number printed on the line.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Delivered quantity.
    - `serialNumbers` (array of string): Serial numbers.
    - `unit` (string): Unit of measure.
    - `vendorArticleNo` (string): The supplier's article number as read.
  - `model` (string): AI model that read the document.
  - `notes` (string): Notes of the extraction.
  - `orderNumbers` (array of string): Order numbers stated on the delivery note.
  - `supplier` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text; only in the single read.
- `id` (string (uuid)): Id of the delivery note.
- `lines` (array of InboundDeliveryNoteLine): Empty in lists.
  - `articleNumber` (string): The masterdata article the line was assigned to.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `mpn` (string): Manufacturer part number.
  - `orderNumber` (string): Purchase order number printed on the line.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Delivered quantity.
  - `serialNumbers` (array of string): Serial numbers.
  - `unit` (string): Unit of measure.
  - `vendorArticleNo` (string): The supplier's article number as read.
- `match` (DeliveryCheck): The check of the delivered lines against the open quantities (ordered − received) of the purchase order.
  - `discrepancies` (array of LockReason): `MINDERLIEFERUNG` (partial delivery, not blocking), `MEHRLIEFERUNG` (more than open), `UNBEKANNTE_POSITION`, `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `evaluatedAt` (string (date-time)): When the check ran.
  - `lines` (array of object): Result per delivery note line.
    - `deliveredQty` (number): Quantity delivered.
    - `description` (string): Description of the line.
    - `openQty` (number): Ordered minus received before this note.
    - `orderedQty` (number): Quantity ordered.
    - `poLineId` (string (uuid)): Empty when the line is not on the order.
    - `poPosition` (integer): Position on the purchase order.
    - `position` (integer): Position number of the line.
    - `result` (string): Result of the line. (one of `OK`, `SHORT`, `OVER`, `UNKNOWN_POSITION`)
    - `variance` (number): Delivered minus open (negative: partial delivery).
  - `status` (string): Outcome of the check against the purchase order. (one of `matched`, `discrepancy`)
  - `uncoveredPoPositions` (array of integer): Positions of order lines with an open quantity the note does not deliver at all (a partial delivery of the order; no discrepancy).
- `orderReference` (string): Order numbers named on the note.
- `posting` (object): The goods receipt posted from the delivery note.
  - `goodsReceiptId` (string (uuid)): Id of the goods receipt.
  - `grNumber` (string): Number of the goods receipt.
  - `postedAt` (string (date-time)): When it was posted.
  - `postedBy` (string): Who posted it.
- `purchaseOrderFixed` (boolean): A person chose the purchase order.
- `purchaseOrderId` (string (uuid)): Purchase order the delivery note was assigned to.
- `purchaseOrderNumber` (string): Number of the purchase order.
- `source` (string): `egis` for a delivery note EGIS reported for an order sent through it (structured, with serial numbers; no document, no AI reading). (one of `egis`)
- `status` (InboundDeliveryNoteStatus): `RECEIVED` waits for the text, `EXTRACTED` is read, `MATCHED` / `DISCREPANCY` checked against the purchase order (findings in `match.discrepancies`), `POSTED` booked as goods receipt, `FAILED` could not be read (`error`, retry with reprocess), `REJECTED` discarded by a person. (one of `RECEIVED`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `POSTED`, `REJECTED`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierAssignment` (object): How the supplier was found.
  - `confidence` (number): Confidence of the assignment (0–1).
  - `evidence` (string): What the assignment is based on.
  - `method` (string): How the supplier was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`.
- `supplierName` (string): Name of the supplier.
- `transactionNumber` (string): Internal number of the delivery note (e.g. `LE-2026-00001`).
- `updatedAt` (string (date-time)): When the delivery note was last changed.

Example 200 answer:

```json
{
  "autoPost": {
    "eligible": true,
    "evaluatedAt": "2026-11-18T10:02:30Z",
    "mode": "dryRun",
    "posted": false,
    "reasons": [],
    "rule": "Lieferschein deckt die Bestellung BE-2026-00068 vollständig (KI-Konfidenz 0,96 ≥ 0,90)."
  },
  "createdAt": "2026-11-18T10:01:00Z",
  "deliveryDate": "2026-11-18",
  "deliveryNoteNumber": "LS-778812",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b11",
  "extraction": {
    "confidence": 0.96,
    "customerNumber": "204711",
    "deliveryDate": "2026-11-18",
    "deliveryNoteNumber": "LS-778812",
    "lines": [
      {
        "articleNumber": "NW-2004",
        "description": "Netzwerkschrank 19 Zoll 12 HE",
        "orderNumber": "BE-2026-00068",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
        "quantity": 1,
        "serialNumbers": [
          "RK12-26-0457"
        ],
        "unit": "STK",
        "vendorArticleNo": "KW-RACK12HE"
      },
      {
        "articleNumber": "NW-2005",
        "description": "Verlegekabel Cat.7 Simplex, 100 m",
        "orderNumber": "BE-2026-00068",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
        "quantity": 3,
        "serialNumbers": [],
        "unit": "PAK",
        "vendorArticleNo": "KW-CAT7-100"
      }
    ],
    "model": "medium",
    "orderNumbers": [
      "BE-2026-00068"
    ],
    "supplier": {
      "city": "Augsburg",
      "country": "DE",
      "name": "Kabelwerk Süd GmbH",
      "street": "Gewerbering 7",
      "vatId": "DE701000002",
      "zip": "86167"
    }
  },
  "id": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a01",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "orderNumber": "BE-2026-00068",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "quantity": 1,
      "serialNumbers": [
        "RK12-26-0457"
      ],
      "unit": "STK",
      "vendorArticleNo": "KW-RACK12HE"
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "orderNumber": "BE-2026-00068",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "quantity": 3,
      "serialNumbers": [],
      "unit": "PAK",
      "vendorArticleNo": "KW-CAT7-100"
    }
  ],
  "match": {
    "discrepancies": [],
    "evaluatedAt": "2026-11-18T10:02:30Z",
    "lines": [
      {
        "deliveredQty": 1,
        "description": "Netzwerkschrank 19 Zoll 12 HE",
        "openQty": 1,
        "orderedQty": 1,
        "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
        "poPosition": 1,
        "position": 1,
        "result": "OK",
        "variance": 0
      },
      {
        "deliveredQty": 3,
        "description": "Verlegekabel Cat.7 Simplex, 100 m",
        "openQty": 3,
        "orderedQty": 3,
        "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
        "poPosition": 2,
        "position": 2,
        "result": "OK",
        "variance": 0
      }
    ],
    "status": "matched",
    "uncoveredPoPositions": []
  },
  "orderReference": "BE-2026-00068",
  "purchaseOrderFixed": false,
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "purchaseOrderNumber": "BE-2026-00068",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierAssignment": {
    "confidence": 1,
    "evidence": "USt-IdNr. DE701000002",
    "method": "exact_vat"
  },
  "supplierName": "Kabelwerk Süd GmbH",
  "transactionNumber": "LE-2026-00012",
  "updatedAt": "2026-11-18T10:02:30Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-delivery-notes/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/match' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Read a delivery note again (tenant:trade:purchasing:write)

`POST /api/trade/v1/inbound-delivery-notes/{id}/reprocess`

Module: Trade · operationId: `reprocessInboundDeliveryNote` · Tag: Inbound delivery notes · Auth: access token (`Authorization: Bearer <accessToken>`)

Reads the DMS document again with AI and checks it; a purchase order a person chose is kept. Not for posted or rejected notes.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The delivery note (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)
- **409** The current state does not allow the action (`code` `invalid_state` or `blocked`). (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `autoPost` (AutoPostDecision): Verdict of the automatic goods receipt on an inbound delivery note, stored whenever the mode is not `off`.
  - `eligible` (boolean): Every condition holds: matched without discrepancy, every line on the order and delivered completely, from EGIS (per shipment) or read with enough confidence and covering every open line of the order (`match.uncoveredPoPositions` empty), order not chosen by a person.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic goods receipt when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `posted` (boolean): The system posted the goods receipt (mode `on`).
  - `reasons` (array of string): Each failed condition (German text).
  - `rule` (string): The rule an automatic post applied (German text), also in the protocol entry of the posting.
- `createdAt` (string (date-time)): When the delivery note was created.
- `deliveryDate` (string (date)): Delivery date.
- `deliveryNoteNumber` (string): The supplier's number.
- `dmsDocumentId` (string (uuid)): Missing for delivery notes EGIS reported (`source` egis).
- `error` (string): Why processing failed.
- `externalReference` (string): `egis:<EGIS order number>:<EGIS delivery note id>` for EGIS delivery notes (one per order the note covers).
- `extraction` (object): What the AI read; never changed afterwards. Not in lists.
  - `confidence` (number): Confidence of the extraction (0–1).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): The supplier's delivery note number.
  - `lines` (array of InboundDeliveryNoteLine): Lines read from the document.
    - `articleNumber` (string): The masterdata article the line was assigned to.
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `mpn` (string): Manufacturer part number.
    - `orderNumber` (string): Purchase order number printed on the line.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Delivered quantity.
    - `serialNumbers` (array of string): Serial numbers.
    - `unit` (string): Unit of measure.
    - `vendorArticleNo` (string): The supplier's article number as read.
  - `model` (string): AI model that read the document.
  - `notes` (string): Notes of the extraction.
  - `orderNumbers` (array of string): Order numbers stated on the delivery note.
  - `supplier` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text; only in the single read.
- `id` (string (uuid)): Id of the delivery note.
- `lines` (array of InboundDeliveryNoteLine): Empty in lists.
  - `articleNumber` (string): The masterdata article the line was assigned to.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `mpn` (string): Manufacturer part number.
  - `orderNumber` (string): Purchase order number printed on the line.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Delivered quantity.
  - `serialNumbers` (array of string): Serial numbers.
  - `unit` (string): Unit of measure.
  - `vendorArticleNo` (string): The supplier's article number as read.
- `match` (DeliveryCheck): The check of the delivered lines against the open quantities (ordered − received) of the purchase order.
  - `discrepancies` (array of LockReason): `MINDERLIEFERUNG` (partial delivery, not blocking), `MEHRLIEFERUNG` (more than open), `UNBEKANNTE_POSITION`, `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `evaluatedAt` (string (date-time)): When the check ran.
  - `lines` (array of object): Result per delivery note line.
    - `deliveredQty` (number): Quantity delivered.
    - `description` (string): Description of the line.
    - `openQty` (number): Ordered minus received before this note.
    - `orderedQty` (number): Quantity ordered.
    - `poLineId` (string (uuid)): Empty when the line is not on the order.
    - `poPosition` (integer): Position on the purchase order.
    - `position` (integer): Position number of the line.
    - `result` (string): Result of the line. (one of `OK`, `SHORT`, `OVER`, `UNKNOWN_POSITION`)
    - `variance` (number): Delivered minus open (negative: partial delivery).
  - `status` (string): Outcome of the check against the purchase order. (one of `matched`, `discrepancy`)
  - `uncoveredPoPositions` (array of integer): Positions of order lines with an open quantity the note does not deliver at all (a partial delivery of the order; no discrepancy).
- `orderReference` (string): Order numbers named on the note.
- `posting` (object): The goods receipt posted from the delivery note.
  - `goodsReceiptId` (string (uuid)): Id of the goods receipt.
  - `grNumber` (string): Number of the goods receipt.
  - `postedAt` (string (date-time)): When it was posted.
  - `postedBy` (string): Who posted it.
- `purchaseOrderFixed` (boolean): A person chose the purchase order.
- `purchaseOrderId` (string (uuid)): Purchase order the delivery note was assigned to.
- `purchaseOrderNumber` (string): Number of the purchase order.
- `source` (string): `egis` for a delivery note EGIS reported for an order sent through it (structured, with serial numbers; no document, no AI reading). (one of `egis`)
- `status` (InboundDeliveryNoteStatus): `RECEIVED` waits for the text, `EXTRACTED` is read, `MATCHED` / `DISCREPANCY` checked against the purchase order (findings in `match.discrepancies`), `POSTED` booked as goods receipt, `FAILED` could not be read (`error`, retry with reprocess), `REJECTED` discarded by a person. (one of `RECEIVED`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `POSTED`, `REJECTED`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierAssignment` (object): How the supplier was found.
  - `confidence` (number): Confidence of the assignment (0–1).
  - `evidence` (string): What the assignment is based on.
  - `method` (string): How the supplier was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`.
- `supplierName` (string): Name of the supplier.
- `transactionNumber` (string): Internal number of the delivery note (e.g. `LE-2026-00001`).
- `updatedAt` (string (date-time)): When the delivery note was last changed.

Example 200 answer:

```json
{
  "autoPost": {
    "eligible": true,
    "evaluatedAt": "2026-11-18T10:02:30Z",
    "mode": "dryRun",
    "posted": false,
    "reasons": [],
    "rule": "Lieferschein deckt die Bestellung BE-2026-00068 vollständig (KI-Konfidenz 0,96 ≥ 0,90)."
  },
  "createdAt": "2026-11-18T10:01:00Z",
  "deliveryDate": "2026-11-18",
  "deliveryNoteNumber": "LS-778812",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b11",
  "extraction": {
    "confidence": 0.96,
    "customerNumber": "204711",
    "deliveryDate": "2026-11-18",
    "deliveryNoteNumber": "LS-778812",
    "lines": [
      {
        "articleNumber": "NW-2004",
        "description": "Netzwerkschrank 19 Zoll 12 HE",
        "orderNumber": "BE-2026-00068",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
        "quantity": 1,
        "serialNumbers": [
          "RK12-26-0457"
        ],
        "unit": "STK",
        "vendorArticleNo": "KW-RACK12HE"
      },
      {
        "articleNumber": "NW-2005",
        "description": "Verlegekabel Cat.7 Simplex, 100 m",
        "orderNumber": "BE-2026-00068",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
        "quantity": 3,
        "serialNumbers": [],
        "unit": "PAK",
        "vendorArticleNo": "KW-CAT7-100"
      }
    ],
    "model": "medium",
    "orderNumbers": [
      "BE-2026-00068"
    ],
    "supplier": {
      "city": "Augsburg",
      "country": "DE",
      "name": "Kabelwerk Süd GmbH",
      "street": "Gewerbering 7",
      "vatId": "DE701000002",
      "zip": "86167"
    }
  },
  "id": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a01",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "orderNumber": "BE-2026-00068",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "quantity": 1,
      "serialNumbers": [
        "RK12-26-0457"
      ],
      "unit": "STK",
      "vendorArticleNo": "KW-RACK12HE"
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "orderNumber": "BE-2026-00068",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "quantity": 3,
      "serialNumbers": [],
      "unit": "PAK",
      "vendorArticleNo": "KW-CAT7-100"
    }
  ],
  "match": {
    "discrepancies": [],
    "evaluatedAt": "2026-11-18T10:02:30Z",
    "lines": [
      {
        "deliveredQty": 1,
        "description": "Netzwerkschrank 19 Zoll 12 HE",
        "openQty": 1,
        "orderedQty": 1,
        "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
        "poPosition": 1,
        "position": 1,
        "result": "OK",
        "variance": 0
      },
      {
        "deliveredQty": 3,
        "description": "Verlegekabel Cat.7 Simplex, 100 m",
        "openQty": 3,
        "orderedQty": 3,
        "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
        "poPosition": 2,
        "position": 2,
        "result": "OK",
        "variance": 0
      }
    ],
    "status": "matched",
    "uncoveredPoPositions": []
  },
  "orderReference": "BE-2026-00068",
  "purchaseOrderFixed": false,
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "purchaseOrderNumber": "BE-2026-00068",
  "status": "MATCHED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierAssignment": {
    "confidence": 1,
    "evidence": "USt-IdNr. DE701000002",
    "method": "exact_vat"
  },
  "supplierName": "Kabelwerk Süd GmbH",
  "transactionNumber": "LE-2026-00012",
  "updatedAt": "2026-11-18T10:02:30Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-delivery-notes/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/reprocess' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Discard a delivery note (tenant:trade:purchasing:write)

`POST /api/trade/v1/inbound-delivery-notes/{id}/reject`

Module: Trade · operationId: `rejectInboundDeliveryNote` · Tag: Inbound delivery notes · Auth: access token (`Authorization: Bearer <accessToken>`)

For documents that are no delivery note or came twice. The comment is recorded in the Verlauf. Not for posted notes.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `comment` (string, required): (max length 1000)

Example:

```json
{
  "comment": "Doppelt eingegangen – identisch mit LE-2026-00012."
}
```

### Responses

- **200** The delivery note (`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 current state does not allow the action (`code` `invalid_state` or `blocked`). (`application/json`)

Fields of the 200 answer:

- `autoPost` (AutoPostDecision): Verdict of the automatic goods receipt on an inbound delivery note, stored whenever the mode is not `off`.
  - `eligible` (boolean): Every condition holds: matched without discrepancy, every line on the order and delivered completely, from EGIS (per shipment) or read with enough confidence and covering every open line of the order (`match.uncoveredPoPositions` empty), order not chosen by a person.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic goods receipt when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `posted` (boolean): The system posted the goods receipt (mode `on`).
  - `reasons` (array of string): Each failed condition (German text).
  - `rule` (string): The rule an automatic post applied (German text), also in the protocol entry of the posting.
- `createdAt` (string (date-time)): When the delivery note was created.
- `deliveryDate` (string (date)): Delivery date.
- `deliveryNoteNumber` (string): The supplier's number.
- `dmsDocumentId` (string (uuid)): Missing for delivery notes EGIS reported (`source` egis).
- `error` (string): Why processing failed.
- `externalReference` (string): `egis:<EGIS order number>:<EGIS delivery note id>` for EGIS delivery notes (one per order the note covers).
- `extraction` (object): What the AI read; never changed afterwards. Not in lists.
  - `confidence` (number): Confidence of the extraction (0–1).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): The supplier's delivery note number.
  - `lines` (array of InboundDeliveryNoteLine): Lines read from the document.
    - `articleNumber` (string): The masterdata article the line was assigned to.
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `mpn` (string): Manufacturer part number.
    - `orderNumber` (string): Purchase order number printed on the line.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Delivered quantity.
    - `serialNumbers` (array of string): Serial numbers.
    - `unit` (string): Unit of measure.
    - `vendorArticleNo` (string): The supplier's article number as read.
  - `model` (string): AI model that read the document.
  - `notes` (string): Notes of the extraction.
  - `orderNumbers` (array of string): Order numbers stated on the delivery note.
  - `supplier` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text; only in the single read.
- `id` (string (uuid)): Id of the delivery note.
- `lines` (array of InboundDeliveryNoteLine): Empty in lists.
  - `articleNumber` (string): The masterdata article the line was assigned to.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `mpn` (string): Manufacturer part number.
  - `orderNumber` (string): Purchase order number printed on the line.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Delivered quantity.
  - `serialNumbers` (array of string): Serial numbers.
  - `unit` (string): Unit of measure.
  - `vendorArticleNo` (string): The supplier's article number as read.
- `match` (DeliveryCheck): The check of the delivered lines against the open quantities (ordered − received) of the purchase order.
  - `discrepancies` (array of LockReason): `MINDERLIEFERUNG` (partial delivery, not blocking), `MEHRLIEFERUNG` (more than open), `UNBEKANNTE_POSITION`, `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `evaluatedAt` (string (date-time)): When the check ran.
  - `lines` (array of object): Result per delivery note line.
    - `deliveredQty` (number): Quantity delivered.
    - `description` (string): Description of the line.
    - `openQty` (number): Ordered minus received before this note.
    - `orderedQty` (number): Quantity ordered.
    - `poLineId` (string (uuid)): Empty when the line is not on the order.
    - `poPosition` (integer): Position on the purchase order.
    - `position` (integer): Position number of the line.
    - `result` (string): Result of the line. (one of `OK`, `SHORT`, `OVER`, `UNKNOWN_POSITION`)
    - `variance` (number): Delivered minus open (negative: partial delivery).
  - `status` (string): Outcome of the check against the purchase order. (one of `matched`, `discrepancy`)
  - `uncoveredPoPositions` (array of integer): Positions of order lines with an open quantity the note does not deliver at all (a partial delivery of the order; no discrepancy).
- `orderReference` (string): Order numbers named on the note.
- `posting` (object): The goods receipt posted from the delivery note.
  - `goodsReceiptId` (string (uuid)): Id of the goods receipt.
  - `grNumber` (string): Number of the goods receipt.
  - `postedAt` (string (date-time)): When it was posted.
  - `postedBy` (string): Who posted it.
- `purchaseOrderFixed` (boolean): A person chose the purchase order.
- `purchaseOrderId` (string (uuid)): Purchase order the delivery note was assigned to.
- `purchaseOrderNumber` (string): Number of the purchase order.
- `source` (string): `egis` for a delivery note EGIS reported for an order sent through it (structured, with serial numbers; no document, no AI reading). (one of `egis`)
- `status` (InboundDeliveryNoteStatus): `RECEIVED` waits for the text, `EXTRACTED` is read, `MATCHED` / `DISCREPANCY` checked against the purchase order (findings in `match.discrepancies`), `POSTED` booked as goods receipt, `FAILED` could not be read (`error`, retry with reprocess), `REJECTED` discarded by a person. (one of `RECEIVED`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `POSTED`, `REJECTED`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierAssignment` (object): How the supplier was found.
  - `confidence` (number): Confidence of the assignment (0–1).
  - `evidence` (string): What the assignment is based on.
  - `method` (string): How the supplier was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`.
- `supplierName` (string): Name of the supplier.
- `transactionNumber` (string): Internal number of the delivery note (e.g. `LE-2026-00001`).
- `updatedAt` (string (date-time)): When the delivery note was last changed.

Example 200 answer:

```json
{
  "createdAt": "2026-11-18T11:00:00Z",
  "deliveryDate": "2026-11-18",
  "deliveryNoteNumber": "LS-778812",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b13",
  "id": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a03",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "orderNumber": "BE-2026-00068",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "quantity": 1,
      "serialNumbers": [
        "RK12-26-0457"
      ],
      "unit": "STK",
      "vendorArticleNo": "KW-RACK12HE"
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "orderNumber": "BE-2026-00068",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "quantity": 3,
      "serialNumbers": [],
      "unit": "PAK",
      "vendorArticleNo": "KW-CAT7-100"
    }
  ],
  "status": "REJECTED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierName": "Kabelwerk Süd GmbH",
  "transactionNumber": "LE-2026-00014",
  "updatedAt": "2026-11-18T11:20:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-delivery-notes/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/reject' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"comment":"Doppelt eingegangen – identisch mit LE-2026-00012."}'
```

## Post the goods receipt of a delivery note (tenant:delivery-note:post)

`POST /api/trade/v1/inbound-delivery-notes/{id}/post`

Module: Trade · operationId: `postInboundDeliveryNote` · Tag: Inbound delivery notes · Auth: access token (`Authorization: Bearer <accessToken>`)

Books a goods receipt (`WE-…`, numbered by trade) against the assigned purchase order with the
confirmed quantity per order line; without `lines` every line found on the order is posted with its
delivered quantity. A quantity may not exceed what is still open on the order line (`422`). The
receipt and the posted delivery note commit together: a note is posted once, and posting a posted
note answers it unchanged. Afterwards the inbound invoices of the order are checked again
(`FEHLENDER_WARENEINGANG`) and the DMS document is linked to the receipt. Publishes
`trade.goodsreceipt.created` and `trade.inbounddeliverynote.posted` (`auto: false`; a note that matches its
order exactly may be posted by the system instead, see `autoPost`, with `auto: true`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `lines` (array of object)
  - `poLineId` (string (uuid), required)
  - `receivedQty` (number, required): 0 leaves the line out.
- `note` (string): Note of the goods receipt; default „Lieferschein <number> (<supplier number>)“. (max length 1000)

Example:

```json
{
  "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."
}
```

### Responses

- **200** The posted delivery note (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The note is not checked yet or rejected, or the purchase order is draft, closed or cancelled. (`application/json`)
- **422** No purchase order assigned, nothing to post, or a quantity exceeds what is open. (`application/json`)
- **423** An active workflow locks the transaction. (`application/json`)

Fields of the 200 answer:

- `autoPost` (AutoPostDecision): Verdict of the automatic goods receipt on an inbound delivery note, stored whenever the mode is not `off`.
  - `eligible` (boolean): Every condition holds: matched without discrepancy, every line on the order and delivered completely, from EGIS (per shipment) or read with enough confidence and covering every open line of the order (`match.uncoveredPoPositions` empty), order not chosen by a person.
  - `evaluatedAt` (string (date-time)): When the decision was evaluated.
  - `mode` (string): Mode of the automatic goods receipt when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
  - `posted` (boolean): The system posted the goods receipt (mode `on`).
  - `reasons` (array of string): Each failed condition (German text).
  - `rule` (string): The rule an automatic post applied (German text), also in the protocol entry of the posting.
- `createdAt` (string (date-time)): When the delivery note was created.
- `deliveryDate` (string (date)): Delivery date.
- `deliveryNoteNumber` (string): The supplier's number.
- `dmsDocumentId` (string (uuid)): Missing for delivery notes EGIS reported (`source` egis).
- `error` (string): Why processing failed.
- `externalReference` (string): `egis:<EGIS order number>:<EGIS delivery note id>` for EGIS delivery notes (one per order the note covers).
- `extraction` (object): What the AI read; never changed afterwards. Not in lists.
  - `confidence` (number): Confidence of the extraction (0–1).
  - `customerNumber` (string): Our customer number at the supplier.
  - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
  - `deliveryNoteNumber` (string): The supplier's delivery note number.
  - `lines` (array of InboundDeliveryNoteLine): Lines read from the document.
    - `articleNumber` (string): The masterdata article the line was assigned to.
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `mpn` (string): Manufacturer part number.
    - `orderNumber` (string): Purchase order number printed on the line.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Delivered quantity.
    - `serialNumbers` (array of string): Serial numbers.
    - `unit` (string): Unit of measure.
    - `vendorArticleNo` (string): The supplier's article number as read.
  - `model` (string): AI model that read the document.
  - `notes` (string): Notes of the extraction.
  - `orderNumbers` (array of string): Order numbers stated on the delivery note.
  - `supplier` (Party)
    - `address` (string): Single-line address (e-invoice).
    - `city` (string): City.
    - `country` (string): Country.
    - `iban` (string): IBAN.
    - `name` (string): Name.
    - `street` (string): Street and house number.
    - `taxNumber` (string): Tax number.
    - `vatId` (string): VAT identification number.
    - `zip` (string): Postal code.
- `fullText` (string): OCR text; only in the single read.
- `id` (string (uuid)): Id of the delivery note.
- `lines` (array of InboundDeliveryNoteLine): Empty in lists.
  - `articleNumber` (string): The masterdata article the line was assigned to.
  - `description` (string): Description of the line.
  - `ean` (string): EAN (GTIN) of the article.
  - `mpn` (string): Manufacturer part number.
  - `orderNumber` (string): Purchase order number printed on the line.
  - `position` (integer): Position number of the line.
  - `productId` (string): Masterdata article (product) id.
  - `quantity` (number): Delivered quantity.
  - `serialNumbers` (array of string): Serial numbers.
  - `unit` (string): Unit of measure.
  - `vendorArticleNo` (string): The supplier's article number as read.
- `match` (DeliveryCheck): The check of the delivered lines against the open quantities (ordered − received) of the purchase order.
  - `discrepancies` (array of LockReason): `MINDERLIEFERUNG` (partial delivery, not blocking), `MEHRLIEFERUNG` (more than open), `UNBEKANNTE_POSITION`, `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `evaluatedAt` (string (date-time)): When the check ran.
  - `lines` (array of object): Result per delivery note line.
    - `deliveredQty` (number): Quantity delivered.
    - `description` (string): Description of the line.
    - `openQty` (number): Ordered minus received before this note.
    - `orderedQty` (number): Quantity ordered.
    - `poLineId` (string (uuid)): Empty when the line is not on the order.
    - `poPosition` (integer): Position on the purchase order.
    - `position` (integer): Position number of the line.
    - `result` (string): Result of the line. (one of `OK`, `SHORT`, `OVER`, `UNKNOWN_POSITION`)
    - `variance` (number): Delivered minus open (negative: partial delivery).
  - `status` (string): Outcome of the check against the purchase order. (one of `matched`, `discrepancy`)
  - `uncoveredPoPositions` (array of integer): Positions of order lines with an open quantity the note does not deliver at all (a partial delivery of the order; no discrepancy).
- `orderReference` (string): Order numbers named on the note.
- `posting` (object): The goods receipt posted from the delivery note.
  - `goodsReceiptId` (string (uuid)): Id of the goods receipt.
  - `grNumber` (string): Number of the goods receipt.
  - `postedAt` (string (date-time)): When it was posted.
  - `postedBy` (string): Who posted it.
- `purchaseOrderFixed` (boolean): A person chose the purchase order.
- `purchaseOrderId` (string (uuid)): Purchase order the delivery note was assigned to.
- `purchaseOrderNumber` (string): Number of the purchase order.
- `source` (string): `egis` for a delivery note EGIS reported for an order sent through it (structured, with serial numbers; no document, no AI reading). (one of `egis`)
- `status` (InboundDeliveryNoteStatus): `RECEIVED` waits for the text, `EXTRACTED` is read, `MATCHED` / `DISCREPANCY` checked against the purchase order (findings in `match.discrepancies`), `POSTED` booked as goods receipt, `FAILED` could not be read (`error`, retry with reprocess), `REJECTED` discarded by a person. (one of `RECEIVED`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `POSTED`, `REJECTED`, `FAILED`)
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
- `supplierAssignment` (object): How the supplier was found.
  - `confidence` (number): Confidence of the assignment (0–1).
  - `evidence` (string): What the assignment is based on.
  - `method` (string): How the supplier was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`.
- `supplierName` (string): Name of the supplier.
- `transactionNumber` (string): Internal number of the delivery note (e.g. `LE-2026-00001`).
- `updatedAt` (string (date-time)): When the delivery note was last changed.

Example 200 answer:

```json
{
  "autoPost": {
    "eligible": true,
    "evaluatedAt": "2026-11-18T10:02:30Z",
    "mode": "dryRun",
    "posted": false,
    "reasons": [],
    "rule": "Lieferschein deckt die Bestellung BE-2026-00068 vollständig (KI-Konfidenz 0,96 ≥ 0,90)."
  },
  "createdAt": "2026-11-18T10:01:00Z",
  "deliveryDate": "2026-11-18",
  "deliveryNoteNumber": "LS-778812",
  "dmsDocumentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b11",
  "extraction": {
    "confidence": 0.96,
    "customerNumber": "204711",
    "deliveryDate": "2026-11-18",
    "deliveryNoteNumber": "LS-778812",
    "lines": [
      {
        "articleNumber": "NW-2004",
        "description": "Netzwerkschrank 19 Zoll 12 HE",
        "orderNumber": "BE-2026-00068",
        "position": 1,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
        "quantity": 1,
        "serialNumbers": [
          "RK12-26-0457"
        ],
        "unit": "STK",
        "vendorArticleNo": "KW-RACK12HE"
      },
      {
        "articleNumber": "NW-2005",
        "description": "Verlegekabel Cat.7 Simplex, 100 m",
        "orderNumber": "BE-2026-00068",
        "position": 2,
        "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
        "quantity": 3,
        "serialNumbers": [],
        "unit": "PAK",
        "vendorArticleNo": "KW-CAT7-100"
      }
    ],
    "model": "medium",
    "orderNumbers": [
      "BE-2026-00068"
    ],
    "supplier": {
      "city": "Augsburg",
      "country": "DE",
      "name": "Kabelwerk Süd GmbH",
      "street": "Gewerbering 7",
      "vatId": "DE701000002",
      "zip": "86167"
    }
  },
  "id": "4e7f8a9b-0c1d-4e2f-9a3b-5c6d7e8f9a01",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "orderNumber": "BE-2026-00068",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "quantity": 1,
      "serialNumbers": [
        "RK12-26-0457"
      ],
      "unit": "STK",
      "vendorArticleNo": "KW-RACK12HE"
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "orderNumber": "BE-2026-00068",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "quantity": 3,
      "serialNumbers": [],
      "unit": "PAK",
      "vendorArticleNo": "KW-CAT7-100"
    }
  ],
  "match": {
    "discrepancies": [],
    "evaluatedAt": "2026-11-18T10:02:30Z",
    "lines": [
      {
        "deliveredQty": 1,
        "description": "Netzwerkschrank 19 Zoll 12 HE",
        "openQty": 1,
        "orderedQty": 1,
        "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
        "poPosition": 1,
        "position": 1,
        "result": "OK",
        "variance": 0
      },
      {
        "deliveredQty": 3,
        "description": "Verlegekabel Cat.7 Simplex, 100 m",
        "openQty": 3,
        "orderedQty": 3,
        "poLineId": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
        "poPosition": 2,
        "position": 2,
        "result": "OK",
        "variance": 0
      }
    ],
    "status": "matched",
    "uncoveredPoPositions": []
  },
  "orderReference": "BE-2026-00068",
  "posting": {
    "goodsReceiptId": "3d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f52",
    "grNumber": "WE-2026-00052",
    "postedAt": "2026-11-18T10:15:00Z",
    "postedBy": "david.richter@muster-it.example"
  },
  "purchaseOrderFixed": false,
  "purchaseOrderId": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "purchaseOrderNumber": "BE-2026-00068",
  "status": "POSTED",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierAssignment": {
    "confidence": 1,
    "evidence": "USt-IdNr. DE701000002",
    "method": "exact_vat"
  },
  "supplierName": "Kabelwerk Süd GmbH",
  "transactionNumber": "LE-2026-00012",
  "updatedAt": "2026-11-18T10:15:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/inbound-delivery-notes/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/post' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"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."}'
```

# Contracts

## List contracts (tenant:trade:contract:read)

`GET /api/trade/v1/contracts`

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

Newest first (creation time, then id), without contingents and links; pages by keyset (`nextCursor`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `search` | query | string |  | Substring of the number, the partner's number or the partner name (case-insensitive). |
| `type` | query | ContractType |  | (one of `CUSTOMER`, `SUPPLIER`) |
| `status` | query | ContractStatus |  | (one of `DRAFT`, `ACTIVE`, `EXPIRED`, `TERMINATED`, `CANCELLED`) |
| `limit` | query | integer |  | 1–100 (else `400 invalid`). (default `50`; max 100) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** A page of contracts (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of Contract, required)
  - `autoRenew` (boolean): The contract renews automatically.
  - `backToBackLinks` (array of BackToBackLink, read-only): Back-to-back links of the contract.
    - `allocatedMargin` (number): Margin allocated to the link.
    - `createdAt` (string (date-time), read-only): When the link was created.
    - `customerContractId` (string (uuid)): Id of the customer contract.
    - `customerNo` (string, read-only): Customer number of the tenant.
    - `id` (string (uuid), read-only): Id of the back-to-back link.
    - `notes` (string): Free-text notes.
    - `supplierContractId` (string (uuid)): Id of the supplier contract.
    - `tenantName` (string, read-only): Name of the tenant.
  - `billingCadence` (string): How often the contract is billed. (one of `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
  - `contingentPots` (array of object): Hour contingents; only written on create.
    - `contractId` (string (uuid), read-only): Id of the contract.
    - `createdAt` (string (date-time), read-only): When the hour contingent was created.
    - `id` (string (uuid), read-only): Id of the hour contingent.
    - `name` (string): Name of the hour contingent.
    - `remainingHours` (number, read-only): Hours left.
    - `rolloverAllowed` (boolean): Unused hours roll over into the next period.
    - `totalHours` (number): Hours of the contingent.
    - `updatedAt` (string (date-time), read-only): When the hour contingent was last changed.
    - `usedHours` (number): Hours used.
    - `validUntil` (string (date-time)): Last day the hours can be used.
  - `contractNumber` (string): `CTR-<n>` when empty on create; never changed by an update.
  - `contractType` (ContractType): (one of `CUSTOMER`, `SUPPLIER`)
  - `createdAt` (string (date-time), read-only): When the contract was created.
  - `cspSubscriptionId` (string): Microsoft CSP subscription of the contract.
  - `cspTenantId` (string): Microsoft CSP tenant.
  - `currency` (string): Currency (ISO 4217).
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `description` (string): Description of the contract.
  - `endDate` (string (date-time)): End of the contract; absent when open-ended.
  - `id` (string (uuid), read-only): Id of the contract.
  - `leasingRate` (number): Leasing rate per billing period.
  - `marginPercentage` (number): Margin in percent.
  - `metadata` (object): Free-form metadata.
  - `netAmount` (number): Net amount per billing period.
  - `noticePeriodDays` (integer): Notice period in days.
  - `partnerId` (string (uuid)): Masterdata address of the partner.
  - `partnerName` (string): Name of the customer or supplier.
  - `startDate` (string (date-time)): Start of the contract.
  - `status` (ContractStatus): (one of `DRAFT`, `ACTIVE`, `EXPIRED`, `TERMINATED`, `CANCELLED`)
  - `tenantName` (string, read-only): Name of the tenant.
  - `title` (string): Title of the contract.
  - `updatedAt` (string (date-time), read-only): When the contract was last changed.
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "autoRenew": true,
      "billingCadence": "MONTHLY",
      "contractNumber": "V-2026-0007",
      "contractType": "CUSTOMER",
      "createdAt": "2025-12-12T10:00:00Z",
      "currency": "EUR",
      "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "netAmount": 180,
      "noticePeriodDays": 90,
      "partnerId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
      "partnerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "startDate": "2026-01-01T00:00:00Z",
      "status": "ACTIVE",
      "title": "Managed Service Arbeitsplätze und Microsoft 365",
      "updatedAt": "2026-10-02T08:15:00Z"
    },
    {
      "autoRenew": true,
      "billingCadence": "MONTHLY",
      "contractNumber": "LV-2026-0003",
      "contractType": "SUPPLIER",
      "createdAt": "2025-12-15T08:00:00Z",
      "currency": "EUR",
      "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
      "netAmount": 79,
      "noticePeriodDays": 30,
      "partnerId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03",
      "partnerName": "CloudNine Hosting AG",
      "startDate": "2026-01-01T00:00:00Z",
      "status": "ACTIVE",
      "title": "Managed Server kanzlei-srv01",
      "updatedAt": "2025-12-15T08:00:00Z"
    }
  ],
  "nextCursor": "Y3JlYXRlZHwyMDI1LTEyLTEyVDEwOjAwOjAwWnwwZTFmMmEzYi00YzVkLTRlNmYtOGE3Yi05YzBkMWUyZjNhMDc"
}
```

### Example request

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

## Create a contract (tenant:trade:contract:write)

`POST /api/trade/v1/contracts`

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

Defaults when empty — `contractNumber` `CTR-<n>`, `contractType` `CUSTOMER`, `status` `DRAFT`, `billingCadence` `MONTHLY`, `currency` `EUR`. `contingentPots` are created with the contract. Publishes `trade.contract.created`.

### Request body

`application/json` (required)

- `autoRenew` (boolean): The contract renews automatically.
- `backToBackLinks` (array of BackToBackLink, read-only): Back-to-back links of the contract.
  - `allocatedMargin` (number): Margin allocated to the link.
  - `createdAt` (string (date-time), read-only): When the link was created.
  - `customerContractId` (string (uuid)): Id of the customer contract.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `id` (string (uuid), read-only): Id of the back-to-back link.
  - `notes` (string): Free-text notes.
  - `supplierContractId` (string (uuid)): Id of the supplier contract.
  - `tenantName` (string, read-only): Name of the tenant.
- `billingCadence` (string): How often the contract is billed. (one of `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `contingentPots` (array of object): Hour contingents; only written on create.
  - `contractId` (string (uuid), read-only): Id of the contract.
  - `createdAt` (string (date-time), read-only): When the hour contingent was created.
  - `id` (string (uuid), read-only): Id of the hour contingent.
  - `name` (string): Name of the hour contingent.
  - `remainingHours` (number, read-only): Hours left.
  - `rolloverAllowed` (boolean): Unused hours roll over into the next period.
  - `totalHours` (number): Hours of the contingent.
  - `updatedAt` (string (date-time), read-only): When the hour contingent was last changed.
  - `usedHours` (number): Hours used.
  - `validUntil` (string (date-time)): Last day the hours can be used.
- `contractNumber` (string): `CTR-<n>` when empty on create; never changed by an update.
- `contractType` (ContractType): (one of `CUSTOMER`, `SUPPLIER`)
- `createdAt` (string (date-time), read-only): When the contract was created.
- `cspSubscriptionId` (string): Microsoft CSP subscription of the contract.
- `cspTenantId` (string): Microsoft CSP tenant.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string, read-only): Customer number of the tenant.
- `description` (string): Description of the contract.
- `endDate` (string (date-time)): End of the contract; absent when open-ended.
- `id` (string (uuid), read-only): Id of the contract.
- `leasingRate` (number): Leasing rate per billing period.
- `marginPercentage` (number): Margin in percent.
- `metadata` (object): Free-form metadata.
- `netAmount` (number): Net amount per billing period.
- `noticePeriodDays` (integer): Notice period in days.
- `partnerId` (string (uuid)): Masterdata address of the partner.
- `partnerName` (string): Name of the customer or supplier.
- `startDate` (string (date-time)): Start of the contract.
- `status` (ContractStatus): (one of `DRAFT`, `ACTIVE`, `EXPIRED`, `TERMINATED`, `CANCELLED`)
- `tenantName` (string, read-only): Name of the tenant.
- `title` (string): Title of the contract.
- `updatedAt` (string (date-time), read-only): When the contract was last changed.

Example:

```json
{
  "autoRenew": true,
  "billingCadence": "MONTHLY",
  "contingentPots": [
    {
      "name": "Supportstunden 2026",
      "rolloverAllowed": false,
      "totalHours": 40,
      "usedHours": 0
    }
  ],
  "contractNumber": "V-2026-0007",
  "contractType": "CUSTOMER",
  "currency": "EUR",
  "netAmount": 490,
  "noticePeriodDays": 90,
  "partnerName": "Muster GmbH",
  "startDate": "2026-01-01T00:00:00Z",
  "status": "ACTIVE",
  "title": "IT-Wartungsvertrag Standard"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 201 answer:

- `autoRenew` (boolean): The contract renews automatically.
- `backToBackLinks` (array of BackToBackLink, read-only): Back-to-back links of the contract.
  - `allocatedMargin` (number): Margin allocated to the link.
  - `createdAt` (string (date-time), read-only): When the link was created.
  - `customerContractId` (string (uuid)): Id of the customer contract.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `id` (string (uuid), read-only): Id of the back-to-back link.
  - `notes` (string): Free-text notes.
  - `supplierContractId` (string (uuid)): Id of the supplier contract.
  - `tenantName` (string, read-only): Name of the tenant.
- `billingCadence` (string): How often the contract is billed. (one of `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `contingentPots` (array of object): Hour contingents; only written on create.
  - `contractId` (string (uuid), read-only): Id of the contract.
  - `createdAt` (string (date-time), read-only): When the hour contingent was created.
  - `id` (string (uuid), read-only): Id of the hour contingent.
  - `name` (string): Name of the hour contingent.
  - `remainingHours` (number, read-only): Hours left.
  - `rolloverAllowed` (boolean): Unused hours roll over into the next period.
  - `totalHours` (number): Hours of the contingent.
  - `updatedAt` (string (date-time), read-only): When the hour contingent was last changed.
  - `usedHours` (number): Hours used.
  - `validUntil` (string (date-time)): Last day the hours can be used.
- `contractNumber` (string): `CTR-<n>` when empty on create; never changed by an update.
- `contractType` (ContractType): (one of `CUSTOMER`, `SUPPLIER`)
- `createdAt` (string (date-time), read-only): When the contract was created.
- `cspSubscriptionId` (string): Microsoft CSP subscription of the contract.
- `cspTenantId` (string): Microsoft CSP tenant.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string, read-only): Customer number of the tenant.
- `description` (string): Description of the contract.
- `endDate` (string (date-time)): End of the contract; absent when open-ended.
- `id` (string (uuid), read-only): Id of the contract.
- `leasingRate` (number): Leasing rate per billing period.
- `marginPercentage` (number): Margin in percent.
- `metadata` (object): Free-form metadata.
- `netAmount` (number): Net amount per billing period.
- `noticePeriodDays` (integer): Notice period in days.
- `partnerId` (string (uuid)): Masterdata address of the partner.
- `partnerName` (string): Name of the customer or supplier.
- `startDate` (string (date-time)): Start of the contract.
- `status` (ContractStatus): (one of `DRAFT`, `ACTIVE`, `EXPIRED`, `TERMINATED`, `CANCELLED`)
- `tenantName` (string, read-only): Name of the tenant.
- `title` (string): Title of the contract.
- `updatedAt` (string (date-time), read-only): When the contract was last changed.

Example 201 answer:

```json
{
  "autoRenew": true,
  "backToBackLinks": [
    {
      "allocatedMargin": 42,
      "createdAt": "2026-01-05T09:00:00Z",
      "customerContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "customerNo": "99999",
      "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d01",
      "notes": "Cloud-Server kanzlei-srv01 bei ITC Riemer",
      "supplierContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
      "tenantName": "DEMO"
    }
  ],
  "billingCadence": "MONTHLY",
  "contingentPots": [
    {
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "createdAt": "2025-12-12T10:00:00Z",
      "id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c01",
      "name": "Supportstunden 2026",
      "remainingHours": 14.5,
      "rolloverAllowed": false,
      "totalHours": 24,
      "updatedAt": "2026-11-14T16:30:00Z",
      "usedHours": 9.5,
      "validUntil": "2026-12-31T00:00:00Z"
    }
  ],
  "contractNumber": "V-2026-0007",
  "contractType": "CUSTOMER",
  "createdAt": "2025-12-12T10:00:00Z",
  "cspTenantId": "8d2f4a6b-1c3e-4f5a-9b7c-0d1e2f3a4b5c",
  "currency": "EUR",
  "customerNo": "99999",
  "description": "Betreuung der 12 Arbeitsplätze, Fernwartung, Microsoft-365-Lizenzen nach Verbrauch und Cloud-Server bei ITC.",
  "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
  "marginPercentage": 18,
  "metadata": {},
  "netAmount": 180,
  "noticePeriodDays": 90,
  "partnerId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "partnerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "startDate": "2026-01-01T00:00:00Z",
  "status": "ACTIVE",
  "tenantName": "DEMO",
  "title": "Managed Service Arbeitsplätze und Microsoft 365",
  "updatedAt": "2026-10-02T08:15:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/contracts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"autoRenew":true,"billingCadence":"MONTHLY","contingentPots":[{"name":"Supportstunden 2026","rolloverAllowed":false,"totalHours":40,"usedHours":0}],"contractNumber":"V-2026-0007","contractType":"CUSTOMER","currency":"EUR","netAmount":490,"noticePeriodDays":90,"partnerName":"Muster GmbH","startDate":"2026-01-01T00:00:00Z","status":"ACTIVE","title":"IT-Wartungsvertrag Standard"}'
```

## Get a contract with contingents and back-to-back links (tenant:trade:contract:read)

`GET /api/trade/v1/contracts/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Contract (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `autoRenew` (boolean): The contract renews automatically.
- `backToBackLinks` (array of BackToBackLink, read-only): Back-to-back links of the contract.
  - `allocatedMargin` (number): Margin allocated to the link.
  - `createdAt` (string (date-time), read-only): When the link was created.
  - `customerContractId` (string (uuid)): Id of the customer contract.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `id` (string (uuid), read-only): Id of the back-to-back link.
  - `notes` (string): Free-text notes.
  - `supplierContractId` (string (uuid)): Id of the supplier contract.
  - `tenantName` (string, read-only): Name of the tenant.
- `billingCadence` (string): How often the contract is billed. (one of `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `contingentPots` (array of object): Hour contingents; only written on create.
  - `contractId` (string (uuid), read-only): Id of the contract.
  - `createdAt` (string (date-time), read-only): When the hour contingent was created.
  - `id` (string (uuid), read-only): Id of the hour contingent.
  - `name` (string): Name of the hour contingent.
  - `remainingHours` (number, read-only): Hours left.
  - `rolloverAllowed` (boolean): Unused hours roll over into the next period.
  - `totalHours` (number): Hours of the contingent.
  - `updatedAt` (string (date-time), read-only): When the hour contingent was last changed.
  - `usedHours` (number): Hours used.
  - `validUntil` (string (date-time)): Last day the hours can be used.
- `contractNumber` (string): `CTR-<n>` when empty on create; never changed by an update.
- `contractType` (ContractType): (one of `CUSTOMER`, `SUPPLIER`)
- `createdAt` (string (date-time), read-only): When the contract was created.
- `cspSubscriptionId` (string): Microsoft CSP subscription of the contract.
- `cspTenantId` (string): Microsoft CSP tenant.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string, read-only): Customer number of the tenant.
- `description` (string): Description of the contract.
- `endDate` (string (date-time)): End of the contract; absent when open-ended.
- `id` (string (uuid), read-only): Id of the contract.
- `leasingRate` (number): Leasing rate per billing period.
- `marginPercentage` (number): Margin in percent.
- `metadata` (object): Free-form metadata.
- `netAmount` (number): Net amount per billing period.
- `noticePeriodDays` (integer): Notice period in days.
- `partnerId` (string (uuid)): Masterdata address of the partner.
- `partnerName` (string): Name of the customer or supplier.
- `startDate` (string (date-time)): Start of the contract.
- `status` (ContractStatus): (one of `DRAFT`, `ACTIVE`, `EXPIRED`, `TERMINATED`, `CANCELLED`)
- `tenantName` (string, read-only): Name of the tenant.
- `title` (string): Title of the contract.
- `updatedAt` (string (date-time), read-only): When the contract was last changed.

Example 200 answer:

```json
{
  "autoRenew": true,
  "backToBackLinks": [
    {
      "allocatedMargin": 42,
      "createdAt": "2026-01-05T09:00:00Z",
      "customerContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "customerNo": "99999",
      "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d01",
      "notes": "Cloud-Server kanzlei-srv01 bei ITC Riemer",
      "supplierContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
      "tenantName": "DEMO"
    }
  ],
  "billingCadence": "MONTHLY",
  "contingentPots": [
    {
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "createdAt": "2025-12-12T10:00:00Z",
      "id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c01",
      "name": "Supportstunden 2026",
      "remainingHours": 14.5,
      "rolloverAllowed": false,
      "totalHours": 24,
      "updatedAt": "2026-11-14T16:30:00Z",
      "usedHours": 9.5,
      "validUntil": "2026-12-31T00:00:00Z"
    }
  ],
  "contractNumber": "V-2026-0007",
  "contractType": "CUSTOMER",
  "createdAt": "2025-12-12T10:00:00Z",
  "cspTenantId": "8d2f4a6b-1c3e-4f5a-9b7c-0d1e2f3a4b5c",
  "currency": "EUR",
  "customerNo": "99999",
  "description": "Betreuung der 12 Arbeitsplätze, Fernwartung, Microsoft-365-Lizenzen nach Verbrauch und Cloud-Server bei ITC.",
  "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
  "marginPercentage": 18,
  "metadata": {},
  "netAmount": 180,
  "noticePeriodDays": 90,
  "partnerId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "partnerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "startDate": "2026-01-01T00:00:00Z",
  "status": "ACTIVE",
  "tenantName": "DEMO",
  "title": "Managed Service Arbeitsplätze und Microsoft 365",
  "updatedAt": "2026-10-02T08:15:00Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/contracts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Replace a contract (tenant:trade:contract:write)

`PUT /api/trade/v1/contracts/{id}`

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

Replaces the contract fields with the body; `contractNumber`, `contingentPots` and `backToBackLinks` are not changed. Publishes `trade.contract.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `autoRenew` (boolean): The contract renews automatically.
- `backToBackLinks` (array of BackToBackLink, read-only): Back-to-back links of the contract.
  - `allocatedMargin` (number): Margin allocated to the link.
  - `createdAt` (string (date-time), read-only): When the link was created.
  - `customerContractId` (string (uuid)): Id of the customer contract.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `id` (string (uuid), read-only): Id of the back-to-back link.
  - `notes` (string): Free-text notes.
  - `supplierContractId` (string (uuid)): Id of the supplier contract.
  - `tenantName` (string, read-only): Name of the tenant.
- `billingCadence` (string): How often the contract is billed. (one of `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `contingentPots` (array of object): Hour contingents; only written on create.
  - `contractId` (string (uuid), read-only): Id of the contract.
  - `createdAt` (string (date-time), read-only): When the hour contingent was created.
  - `id` (string (uuid), read-only): Id of the hour contingent.
  - `name` (string): Name of the hour contingent.
  - `remainingHours` (number, read-only): Hours left.
  - `rolloverAllowed` (boolean): Unused hours roll over into the next period.
  - `totalHours` (number): Hours of the contingent.
  - `updatedAt` (string (date-time), read-only): When the hour contingent was last changed.
  - `usedHours` (number): Hours used.
  - `validUntil` (string (date-time)): Last day the hours can be used.
- `contractNumber` (string): `CTR-<n>` when empty on create; never changed by an update.
- `contractType` (ContractType): (one of `CUSTOMER`, `SUPPLIER`)
- `createdAt` (string (date-time), read-only): When the contract was created.
- `cspSubscriptionId` (string): Microsoft CSP subscription of the contract.
- `cspTenantId` (string): Microsoft CSP tenant.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string, read-only): Customer number of the tenant.
- `description` (string): Description of the contract.
- `endDate` (string (date-time)): End of the contract; absent when open-ended.
- `id` (string (uuid), read-only): Id of the contract.
- `leasingRate` (number): Leasing rate per billing period.
- `marginPercentage` (number): Margin in percent.
- `metadata` (object): Free-form metadata.
- `netAmount` (number): Net amount per billing period.
- `noticePeriodDays` (integer): Notice period in days.
- `partnerId` (string (uuid)): Masterdata address of the partner.
- `partnerName` (string): Name of the customer or supplier.
- `startDate` (string (date-time)): Start of the contract.
- `status` (ContractStatus): (one of `DRAFT`, `ACTIVE`, `EXPIRED`, `TERMINATED`, `CANCELLED`)
- `tenantName` (string, read-only): Name of the tenant.
- `title` (string): Title of the contract.
- `updatedAt` (string (date-time), read-only): When the contract was last changed.

Example:

```json
{
  "autoRenew": true,
  "backToBackLinks": [
    {
      "allocatedMargin": 42,
      "createdAt": "2026-01-05T09:00:00Z",
      "customerContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "customerNo": "99999",
      "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d01",
      "notes": "Cloud-Server kanzlei-srv01 bei ITC Riemer",
      "supplierContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
      "tenantName": "DEMO"
    }
  ],
  "billingCadence": "MONTHLY",
  "contingentPots": [
    {
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "createdAt": "2025-12-12T10:00:00Z",
      "id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c01",
      "name": "Supportstunden 2026",
      "remainingHours": 14.5,
      "rolloverAllowed": false,
      "totalHours": 24,
      "updatedAt": "2026-11-14T16:30:00Z",
      "usedHours": 9.5,
      "validUntil": "2026-12-31T00:00:00Z"
    }
  ],
  "contractNumber": "V-2026-0007",
  "contractType": "CUSTOMER",
  "createdAt": "2025-12-12T10:00:00Z",
  "cspTenantId": "8d2f4a6b-1c3e-4f5a-9b7c-0d1e2f3a4b5c",
  "currency": "EUR",
  "customerNo": "99999",
  "description": "Betreuung der 12 Arbeitsplätze, Fernwartung, Microsoft-365-Lizenzen nach Verbrauch und Cloud-Server bei ITC.",
  "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
  "marginPercentage": 18,
  "metadata": {},
  "netAmount": 180,
  "noticePeriodDays": 90,
  "partnerId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "partnerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "startDate": "2026-01-01T00:00:00Z",
  "status": "ACTIVE",
  "tenantName": "DEMO",
  "title": "Managed Service Arbeitsplätze und Microsoft 365",
  "updatedAt": "2026-10-02T08:15:00Z"
}
```

### Responses

- **200** Updated (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `autoRenew` (boolean): The contract renews automatically.
- `backToBackLinks` (array of BackToBackLink, read-only): Back-to-back links of the contract.
  - `allocatedMargin` (number): Margin allocated to the link.
  - `createdAt` (string (date-time), read-only): When the link was created.
  - `customerContractId` (string (uuid)): Id of the customer contract.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `id` (string (uuid), read-only): Id of the back-to-back link.
  - `notes` (string): Free-text notes.
  - `supplierContractId` (string (uuid)): Id of the supplier contract.
  - `tenantName` (string, read-only): Name of the tenant.
- `billingCadence` (string): How often the contract is billed. (one of `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `contingentPots` (array of object): Hour contingents; only written on create.
  - `contractId` (string (uuid), read-only): Id of the contract.
  - `createdAt` (string (date-time), read-only): When the hour contingent was created.
  - `id` (string (uuid), read-only): Id of the hour contingent.
  - `name` (string): Name of the hour contingent.
  - `remainingHours` (number, read-only): Hours left.
  - `rolloverAllowed` (boolean): Unused hours roll over into the next period.
  - `totalHours` (number): Hours of the contingent.
  - `updatedAt` (string (date-time), read-only): When the hour contingent was last changed.
  - `usedHours` (number): Hours used.
  - `validUntil` (string (date-time)): Last day the hours can be used.
- `contractNumber` (string): `CTR-<n>` when empty on create; never changed by an update.
- `contractType` (ContractType): (one of `CUSTOMER`, `SUPPLIER`)
- `createdAt` (string (date-time), read-only): When the contract was created.
- `cspSubscriptionId` (string): Microsoft CSP subscription of the contract.
- `cspTenantId` (string): Microsoft CSP tenant.
- `currency` (string): Currency (ISO 4217).
- `customerNo` (string, read-only): Customer number of the tenant.
- `description` (string): Description of the contract.
- `endDate` (string (date-time)): End of the contract; absent when open-ended.
- `id` (string (uuid), read-only): Id of the contract.
- `leasingRate` (number): Leasing rate per billing period.
- `marginPercentage` (number): Margin in percent.
- `metadata` (object): Free-form metadata.
- `netAmount` (number): Net amount per billing period.
- `noticePeriodDays` (integer): Notice period in days.
- `partnerId` (string (uuid)): Masterdata address of the partner.
- `partnerName` (string): Name of the customer or supplier.
- `startDate` (string (date-time)): Start of the contract.
- `status` (ContractStatus): (one of `DRAFT`, `ACTIVE`, `EXPIRED`, `TERMINATED`, `CANCELLED`)
- `tenantName` (string, read-only): Name of the tenant.
- `title` (string): Title of the contract.
- `updatedAt` (string (date-time), read-only): When the contract was last changed.

Example 200 answer:

```json
{
  "autoRenew": true,
  "backToBackLinks": [
    {
      "allocatedMargin": 42,
      "createdAt": "2026-01-05T09:00:00Z",
      "customerContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "customerNo": "99999",
      "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d01",
      "notes": "Cloud-Server kanzlei-srv01 bei ITC Riemer",
      "supplierContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
      "tenantName": "DEMO"
    }
  ],
  "billingCadence": "MONTHLY",
  "contingentPots": [
    {
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "createdAt": "2025-12-12T10:00:00Z",
      "id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c01",
      "name": "Supportstunden 2026",
      "remainingHours": 14.5,
      "rolloverAllowed": false,
      "totalHours": 24,
      "updatedAt": "2026-11-14T16:30:00Z",
      "usedHours": 9.5,
      "validUntil": "2026-12-31T00:00:00Z"
    }
  ],
  "contractNumber": "V-2026-0007",
  "contractType": "CUSTOMER",
  "createdAt": "2025-12-12T10:00:00Z",
  "cspTenantId": "8d2f4a6b-1c3e-4f5a-9b7c-0d1e2f3a4b5c",
  "currency": "EUR",
  "customerNo": "99999",
  "description": "Betreuung der 12 Arbeitsplätze, Fernwartung, Microsoft-365-Lizenzen nach Verbrauch und Cloud-Server bei ITC.",
  "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
  "marginPercentage": 18,
  "metadata": {},
  "netAmount": 180,
  "noticePeriodDays": 90,
  "partnerId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "partnerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "startDate": "2026-01-01T00:00:00Z",
  "status": "ACTIVE",
  "tenantName": "DEMO",
  "title": "Managed Service Arbeitsplätze und Microsoft 365",
  "updatedAt": "2026-10-02T08:15:00Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/contracts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"autoRenew":true,"backToBackLinks":[{"allocatedMargin":42,"createdAt":"2026-01-05T09:00:00Z","customerContractId":"0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07","customerNo":"99999","id":"6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d01","notes":"Cloud-Server kanzlei-srv01 bei ITC Riemer","supplierContractId":"0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03","tenantName":"DEMO"}],"billingCadence":"MONTHLY","contingentPots":[{"contractId":"0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07","createdAt":"2025-12-12T10:00:00Z","id":"5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c01","name":"Supportstunden 2026","remainingHours":14.5,"rolloverAllowed":false,"totalHours":24,"updatedAt":"2026-11-14T16:30:00Z","usedHours":9.5,"validUntil":"2026-12-31T00:00:00Z"}],"contractNumber":"V-2026-0007","contractType":"CUSTOMER","createdAt":"2025-12-12T10:00:00Z","cspTenantId":"8d2f4a6b-1c3e-4f5a-9b7c-0d1e2f3a4b5c","currency":"EUR","customerNo":"99999","description":"Betreuung der 12 Arbeitsplätze, Fernwartung, Microsoft-365-Lizenzen nach Verbrauch und Cloud-Server bei ITC.","id":"0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07","marginPercentage":18,"metadata":{},"netAmount":180,"noticePeriodDays":90,"partnerId":"3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02","partnerName":"Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB","startDate":"2026-01-01T00:00:00Z","status":"ACTIVE","tenantName":"DEMO","title":"Managed Service Arbeitsplätze und Microsoft 365","updatedAt":"2026-10-02T08:15:00Z"}'
```

## Delete a contract (tenant:trade:contract:write)

`DELETE /api/trade/v1/contracts/{id}`

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

Publishes `trade.contract.deleted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Deleted (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `status` (string, required): Outcome of the request.

Example 200 answer:

```json
{
  "status": "deleted"
}
```

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/trade/v1/contracts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the recurring positions of a contract (tenant:trade:contract:read or tenant:trade:msp:read)

`GET /api/trade/v1/contracts/{id}/items`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Positions (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `items` (array of ContractItem)

Example 200 answer:

```json
{
  "items": [
    {
      "articleNumber": "DL-9005",
      "billingCadence": "",
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "id": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
      "name": "Supportpauschale Fernwartung, monatlich",
      "quantity": 1,
      "sortOrder": 1,
      "source": "fixed",
      "startDate": "2026-01-01",
      "unitPrice": 180
    },
    {
      "articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
      "billingCadence": "",
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "id": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b02",
      "name": "Microsoft 365 Business Standard",
      "quantity": 1,
      "sortOrder": 2,
      "source": "usage",
      "startDate": "2026-01-01",
      "unitPrice": 12.5
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/contracts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Add a recurring position to a contract (tenant:trade:msp:write)

`POST /api/trade/v1/contracts/{id}/items`

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

`fixed` positions are billed by their cadence (empty: the contract's) from their start (else the contract's);
monthly ones are prorated by days in their first and last month. A `usage` position sets the price of its
article for the contract's usage. MSP drafts become stale.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `articleNumber` (string, required): Article number in masterdata. (max length 100)
- `quantity` (number, required): Quantity per billing period (greater than 0).
- `billingCadence` (string): Empty: the contract's cadence, also after it changes. (one of ``, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `endDate` (string (date)): Last day the position is billed (YYYY-MM-DD).
- `name` (string): Name printed on the invoice; empty uses the article name. (max length 300)
- `sortOrder` (integer): Sort order (ascending).
- `source` (string): `fixed` (the quantity) or `usage` (the collected MSP usage). (one of `fixed`, `usage`; default `"fixed"`)
- `startDate` (string (date)): First day the position is billed (YYYY-MM-DD).
- `unitPrice` (number): Net price; empty: the masterdata article's price.

Example:

```json
{
  "articleNumber": "MS-FLAT",
  "name": "Managed Service Pauschale",
  "quantity": 1,
  "source": "fixed",
  "unitPrice": 310
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The state does not allow it: `month_closed` (an invoice of the month is approved or booked), `msp_disabled`, `collection_incomplete` (not every active connector has collected the month), `run_in_progress`, `itc_not_enabled` and `itc_no_supplier` (upload only), or `conflict` (e.g. a stale draft, open problems, an invoice past draft). (`application/json`)

Fields of the 201 answer:

- `articleNumber` (string, required): Article number in masterdata. (max length 100)
- `quantity` (number, required): Quantity per billing period (greater than 0).
- `billingCadence` (string): Empty: the contract's cadence, also after it changes. (one of ``, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `endDate` (string (date)): Last day the position is billed (YYYY-MM-DD).
- `name` (string): Name printed on the invoice; empty uses the article name. (max length 300)
- `sortOrder` (integer): Sort order (ascending).
- `source` (string): `fixed` (the quantity) or `usage` (the collected MSP usage). (one of `fixed`, `usage`; default `"fixed"`)
- `startDate` (string (date)): First day the position is billed (YYYY-MM-DD).
- `unitPrice` (number): Net price; empty: the masterdata article's price.
- `contractId` (string (uuid)): Id of the contract.
- `id` (string (uuid)): Id of the contract item.

Example 201 answer:

```json
{
  "articleNumber": "DL-9005",
  "billingCadence": "",
  "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
  "id": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
  "name": "Supportpauschale Fernwartung, monatlich",
  "quantity": 1,
  "sortOrder": 1,
  "source": "fixed",
  "startDate": "2026-01-01",
  "unitPrice": 180
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/contracts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"articleNumber":"MS-FLAT","name":"Managed Service Pauschale","quantity":1,"source":"fixed","unitPrice":310}'
```

## Replace a recurring position of a contract (tenant:trade:msp:write)

`PUT /api/trade/v1/contracts/{id}/items/{itemId}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `itemId` | path | string (uuid) | yes |  |

### Request body

`application/json` (required)

- `articleNumber` (string, required): Article number in masterdata. (max length 100)
- `quantity` (number, required): Quantity per billing period (greater than 0).
- `billingCadence` (string): Empty: the contract's cadence, also after it changes. (one of ``, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `endDate` (string (date)): Last day the position is billed (YYYY-MM-DD).
- `name` (string): Name printed on the invoice; empty uses the article name. (max length 300)
- `sortOrder` (integer): Sort order (ascending).
- `source` (string): `fixed` (the quantity) or `usage` (the collected MSP usage). (one of `fixed`, `usage`; default `"fixed"`)
- `startDate` (string (date)): First day the position is billed (YYYY-MM-DD).
- `unitPrice` (number): Net price; empty: the masterdata article's price.

Example:

```json
{
  "articleNumber": "DL-9005",
  "billingCadence": "",
  "name": "Supportpauschale Fernwartung, monatlich",
  "quantity": 1,
  "sortOrder": 1,
  "source": "fixed",
  "startDate": "2026-01-01",
  "unitPrice": 180
}
```

### Responses

- **200** Updated (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The state does not allow it: `month_closed` (an invoice of the month is approved or booked), `msp_disabled`, `collection_incomplete` (not every active connector has collected the month), `run_in_progress`, `itc_not_enabled` and `itc_no_supplier` (upload only), or `conflict` (e.g. a stale draft, open problems, an invoice past draft). (`application/json`)

Fields of the 200 answer:

- `articleNumber` (string, required): Article number in masterdata. (max length 100)
- `quantity` (number, required): Quantity per billing period (greater than 0).
- `billingCadence` (string): Empty: the contract's cadence, also after it changes. (one of ``, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `endDate` (string (date)): Last day the position is billed (YYYY-MM-DD).
- `name` (string): Name printed on the invoice; empty uses the article name. (max length 300)
- `sortOrder` (integer): Sort order (ascending).
- `source` (string): `fixed` (the quantity) or `usage` (the collected MSP usage). (one of `fixed`, `usage`; default `"fixed"`)
- `startDate` (string (date)): First day the position is billed (YYYY-MM-DD).
- `unitPrice` (number): Net price; empty: the masterdata article's price.
- `contractId` (string (uuid)): Id of the contract.
- `id` (string (uuid)): Id of the contract item.

Example 200 answer:

```json
{
  "articleNumber": "DL-9005",
  "billingCadence": "",
  "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
  "id": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
  "name": "Supportpauschale Fernwartung, monatlich",
  "quantity": 1,
  "sortOrder": 1,
  "source": "fixed",
  "startDate": "2026-01-01",
  "unitPrice": 180
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/contracts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/items/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"articleNumber":"DL-9005","billingCadence":"","name":"Supportpauschale Fernwartung, monatlich","quantity":1,"sortOrder":1,"source":"fixed","startDate":"2026-01-01","unitPrice":180}'
```

## Remove a recurring position of a contract (tenant:trade:msp:write)

`DELETE /api/trade/v1/contracts/{id}/items/{itemId}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `itemId` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/trade/v1/contracts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/items/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List back-to-back links (tenant:trade:contract:read)

`GET /api/trade/v1/contracts/back-to-back`

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

Newest first.

### Responses

- **200** Links (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of BackToBackLink, required)
  - `allocatedMargin` (number): Margin allocated to the link.
  - `createdAt` (string (date-time), read-only): When the link was created.
  - `customerContractId` (string (uuid)): Id of the customer contract.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `id` (string (uuid), read-only): Id of the back-to-back link.
  - `notes` (string): Free-text notes.
  - `supplierContractId` (string (uuid)): Id of the supplier contract.
  - `tenantName` (string, read-only): Name of the tenant.

Example 200 answer:

```json
{
  "items": [
    {
      "allocatedMargin": 42,
      "createdAt": "2026-01-05T09:00:00Z",
      "customerContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "customerNo": "99999",
      "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d01",
      "notes": "Cloud-Server kanzlei-srv01 bei ITC Riemer",
      "supplierContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
      "tenantName": "DEMO"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/contracts/back-to-back' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Link a customer contract to a supplier contract (tenant:trade:contract:write)

`POST /api/trade/v1/contracts/back-to-back`

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

Both contracts must be contracts of your tenant; an unknown contract id answers 404.

### Request body

`application/json` (required)

- `allocatedMargin` (number): Margin allocated to the link.
- `createdAt` (string (date-time), read-only): When the link was created.
- `customerContractId` (string (uuid)): Id of the customer contract.
- `customerNo` (string, read-only): Customer number of the tenant.
- `id` (string (uuid), read-only): Id of the back-to-back link.
- `notes` (string): Free-text notes.
- `supplierContractId` (string (uuid)): Id of the supplier contract.
- `tenantName` (string, read-only): Name of the tenant.

Example:

```json
{
  "allocatedMargin": 120,
  "customerContractId": "4b0c2f9e-3d7a-4c55-9a1e-2f6b8d1c0a11",
  "notes": "Microsoft 365 Business Premium",
  "supplierContractId": "8e5d1a2b-6c3f-4e77-b0a9-1d2c3e4f5a66"
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **404** Not found in the tenant. (`application/json`)

Fields of the 201 answer:

- `allocatedMargin` (number): Margin allocated to the link.
- `createdAt` (string (date-time), read-only): When the link was created.
- `customerContractId` (string (uuid)): Id of the customer contract.
- `customerNo` (string, read-only): Customer number of the tenant.
- `id` (string (uuid), read-only): Id of the back-to-back link.
- `notes` (string): Free-text notes.
- `supplierContractId` (string (uuid)): Id of the supplier contract.
- `tenantName` (string, read-only): Name of the tenant.

Example 201 answer:

```json
{
  "allocatedMargin": 42,
  "createdAt": "2026-01-05T09:00:00Z",
  "customerContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
  "customerNo": "99999",
  "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d01",
  "notes": "Cloud-Server kanzlei-srv01 bei ITC Riemer",
  "supplierContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
  "tenantName": "DEMO"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/contracts/back-to-back' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"allocatedMargin":120,"customerContractId":"4b0c2f9e-3d7a-4c55-9a1e-2f6b8d1c0a11","notes":"Microsoft 365 Business Premium","supplierContractId":"8e5d1a2b-6c3f-4e77-b0a9-1d2c3e4f5a66"}'
```

# Usage

## Record service usage (tenant:settings:write)

`POST /api/trade/v1/usage`

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

Publishes a `trade.usage.recorded` event for billing consumers; nothing else is stored.

### Request body

`application/json` (required)

- `quantity` (number, required): Must not be 0.
- `serviceKey` (string, required): Billing key of the service.
- `unit` (string)

Example:

```json
{
  "quantity": 250,
  "serviceKey": "backup-storage",
  "unit": "GB"
}
```

### Responses

- **200** Recorded (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `status` (string, required): Outcome of the request.

Example 200 answer:

```json
{
  "status": "recorded"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/usage' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"quantity":250,"serviceKey":"backup-storage","unit":"GB"}'
```

## Which MSP providers are enabled (signed in)

`GET /api/trade/v1/msp/status`

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

### Responses

- **200** Enabled providers (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `ingram` (boolean, required)
- `mailstore` (boolean, required)
- `sophos` (boolean, required)

Example 200 answer:

```json
{
  "ingram": true,
  "mailstore": true,
  "sophos": true
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/status' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# MSP billing

## Start collecting the MSP usage of a month (tenant:trade:msp:write)

`POST /api/trade/v1/msp/collect`

Module: Trade · operationId: `collectMspUsage` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Claims the run of the month of every enabled provider and answers `202` at once with them as `running`
(`runs[].runId`); the providers are collected in the background, since one may take minutes (Ingram reads
every subscription and waits out its API quota). Follow the outcome with `listMspRuns`. A provider whose run
another collection holds is listed with `errors`. The collection fetches the usage of the month from every
enabled provider (MailStore, Sophos, Ingram – Microsoft CSP is
bought through Ingram; ITC Riemer is uploaded instead, `uploadMspItcReport`), keeps the raw answers in the database (`rawAnswers` of the run) and replaces the provider's items of the month in one
step; a second collection of the same month never duplicates items. After a successful run every item is
published as `trade.usage.recorded` with the run id. A failing provider fails only its run (`runs`, `errors`)
and keeps the items collected before. Year and month come from the body or the query; without them the
previous month (Europe/Berlin) is collected. The scheduler collects the previous month on the first days of
every month by itself. Drafts of the month become stale and must be recomputed.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `year` | query | integer |  |  |
| `month` | query | string |  | Month number, or `YYYY-MM`. |

### Request body

`application/json`

- `month` (integer): (max 12)
- `providers` (array of string): Providers to collect (duplicates count once); only their runs are claimed. Empty or missing collects every enabled provider. A name that is not an enabled provider answers `400` with code `provider_not_enabled`.
- `year` (integer)

Example:

```json
{
  "month": 10,
  "providers": [
    "sophos",
    "ingram"
  ],
  "year": 2026
}
```

### Responses

- **202** Collection started; the claimed runs are `running`, `totalItems` is 0 (`application/json`)
- **400** Invalid request or a provider that is not enabled (code `provider_not_enabled`) (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **409** The state does not allow it: `month_closed` (an invoice of the month is approved or booked), `msp_disabled`, `collection_incomplete` (not every active connector has collected the month), `run_in_progress`, `itc_not_enabled` and `itc_no_supplier` (upload only), or `conflict` (e.g. a stale draft, open problems, an invoice past draft). (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 202 answer:

- `errors` (array of string): Providers that failed or whose run another collection holds.
- `month` (integer): Month (1–12) of the billing month.
- `providersRun` (array of string): Providers collected.
- `runs` (array of object): Run of each provider.
  - `error` (string): Why the run failed.
  - `items` (integer): Number of usage items of the run.
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `runId` (string (uuid)): Id of the usage run.
  - `status` (string): `running`: another collection of the provider and month is running; nothing was done. (one of `running`, `succeeded`, `failed`)
- `totalItems` (integer): Number of usage items collected.
- `year` (integer): Year of the billing month.

Example 202 answer:

```json
{
  "errors": [],
  "month": 10,
  "providersRun": [
    "sophos",
    "ingram"
  ],
  "runs": [
    {
      "items": 0,
      "provider": "sophos",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f02",
      "status": "running"
    },
    {
      "items": 0,
      "provider": "ingram",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
      "status": "running"
    }
  ],
  "totalItems": 0,
  "year": 2026
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/collect' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"month":10,"providers":["sophos","ingram"],"year":2026}'
```

## Upload an ITC Riemer report (tenant:trade:msp:write)

`POST /api/trade/v1/msp/itc/reports`

Module: Trade · operationId: `uploadMspItcReport` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

ITC Riemer has no API: its monthly reports are uploaded (needs `msp.itc.enabled`). The file is scanned for
malware, its kind told by its header (`unknown_report` otherwise, nothing is kept) and filed in DMS under the ITC
supplier address (`msp.itc.supplierAddressId`, else the distributor link `itc`). Each report is the run of its own
connector for the month (`run`): the VM resource report (`vm`, provider `itc`) and the backup job report
(`backup-jobs`, provider `itc-backup`: per job `ITCHVBAKVM` × VMs and `ITCHVBAKGB` × GB) replace their usage of the
month, drafts become stale and are recomputed; so does the backup licence report (`licenses`, provider
`itc-licenses`: per customer `ITCVCSP` × points and `ITCVBAKGB` × storage quota in GB). A month is complete only
with all three. A recognised report that cannot be
read is filed, its run fails with the reason and the answer is 422 `report_unreadable`. Max 5 MB.

### Request body

`multipart/form-data` (required)

- `file` (string (binary), required): The report (CSV), at most 5 MB.
- `month` (string): Billing month `YYYY-MM`; default the previous month (Europe/Berlin).

### Responses

- **200** Report taken (`application/json`)
- **400** No file (`field` `file`) or a month that is not `YYYY-MM` (`field` `month`) (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **409** Not allowed now: `itc_not_enabled`, `itc_no_supplier` (no ITC supplier address: neither `msp.itc.supplierAddressId` nor a distributor link `itc`), `msp_disabled`, `month_closed` (an invoice of the month is approved or booked) or `run_in_progress` (ITC's run of the month is running) (`application/json`)
- **413** The file is larger than 5 MB (code `too_large`) (`application/json`)
- **422** Refused: `unknown_report` (not an ITC Riemer report, nothing kept), `report_unreadable` (recognised but not readable – filed, its run failed with the reason) or `infected` (the malware scan found something) (`application/json`)
- **503** The file could not be scanned and is refused (`scan_failed`), or the trade settings are unavailable (`application/json`)

Fields of the 200 answer:

- `documentId` (string, required): The report's DMS document; empty where no DMS is connected (local runs).
- `kind` (string, required): Kind of the report, told by its header: the run of `itc`, `itc-licenses` or `itc-backup`. (one of `vm`, `licenses`, `backup-jobs`)
- `run` (object): The run of the report's connector for the month.

Example 200 answer:

```json
{
  "documentId": "9f2a3b4c-5d6e-4f7a-8b8c-1d2e3f4a5b31",
  "kind": "vm",
  "run": {
    "items": 6,
    "provider": "itc",
    "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f04",
    "status": "succeeded"
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/itc/reports' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf'
```

## List the price suggestions (tenant:trade:msp:read, tenant:trade:msp:write, tenant:trade:msp:approve, tenant:masterdata:read or tenant:masterdata:write)

`GET /api/trade/v1/msp/price-suggestions`

Module: Trade · operationId: `listMspPriceSuggestions` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

New current Ingram prices of Microsoft articles that wait for a person. The open ones come first, at most 200;
there is no cursor. Needs any one of `tenant:trade:msp:read`, `tenant:trade:msp:write`, `tenant:trade:msp:approve`,
`tenant:masterdata:read`, `tenant:masterdata:write`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string |  | Only suggestions in this state. (one of `open`, `accepted`, `rejected`) |
| `article` | query | string |  | Only suggestions of this article number. |

### Responses

- **200** Suggestions (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `items` (array of MspPriceSuggestion, required)
  - `articleNumber` (string, required): Article number in masterdata.
  - `id` (string (uuid), required): Id of the suggestion.
  - `month` (integer, required): Billing month in which the change was found.
  - `provider` (string, required): The provider the price comes from.
  - `skuKey` (string, required): The provider's SKU key of the article.
  - `status` (string, required): Status of the suggestion (`open`, `accepted`, `rejected`). (one of `open`, `accepted`, `rejected`)
  - `updatedAt` (string (date-time), required): When the suggestion last changed.
  - `year` (integer, required): Billing year in which the change was found.
  - `articleId` (string (uuid)): The masterdata article.
  - `currency` (string): Currency (ISO 4217).
  - `decidedAt` (string (date-time)): When it was accepted or rejected.
  - `decidedBy` (string): Who decided; missing while open.
  - `newPurchase` (number): Suggested purchase price.
  - `newSales` (number): Suggested sales price.
  - `oldPurchase` (number): Purchase price now in masterdata.
  - `oldSales` (number): Sales price now in masterdata.
  - `priceSince` (string (date-time)): The new price applies since.
  - `subscriptionId` (string): The subscription the price was read from.
  - `supplierAddressId` (string (uuid)): Masterdata address of the supplier.

Example 200 answer:

```json
{
  "items": [
    {
      "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7f21",
      "articleNumber": "MSFTCFQ7TTC0LCHC0002P1YM",
      "currency": "EUR",
      "id": "6e7f8a9b-0c1d-4e2f-8a3b-4c5d6e7f8a01",
      "month": 10,
      "newPurchase": 18,
      "newSales": 21.6,
      "oldPurchase": 17.2,
      "oldSales": 20.6,
      "priceSince": "2026-11-01T00:00:00Z",
      "provider": "ingram",
      "skuKey": "CFQ7TTC0LCHC:0002/P1YM",
      "status": "open",
      "subscriptionId": "1700012399",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10",
      "updatedAt": "2026-11-01T05:04:40Z",
      "year": 2026
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/price-suggestions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Accept a price suggestion (tenant:trade:msp:write, tenant:trade:msp:approve or tenant:masterdata:write)

`POST /api/trade/v1/msp/price-suggestions/{id}/accept`

Module: Trade · operationId: `acceptMspPriceSuggestion` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Writes the suggested sales and purchase price to the article in masterdata and marks the suggestion accepted.
Needs any one of `tenant:trade:msp:write`, `tenant:trade:msp:approve`, `tenant:masterdata:write`. A suggestion is decided once: a second decision answers 409 `price_suggestion_decided`; one a run changed since it was read answers 409 `price_suggestion_changed`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The decided suggestion (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** Already decided (`price_suggestion_decided`), changed by a run since it was read (`price_suggestion_changed`) or – accept only – the article has other prices in masterdata by now (`price_changed`, nothing written) (`application/json`)
- **502** Masterdata refused the prices (`masterdata_refused`); the suggestion stays open (`application/json`)

Fields of the 200 answer:

- `articleNumber` (string, required): Article number in masterdata.
- `id` (string (uuid), required): Id of the suggestion.
- `month` (integer, required): Billing month in which the change was found.
- `provider` (string, required): The provider the price comes from.
- `skuKey` (string, required): The provider's SKU key of the article.
- `status` (string, required): Status of the suggestion (`open`, `accepted`, `rejected`). (one of `open`, `accepted`, `rejected`)
- `updatedAt` (string (date-time), required): When the suggestion last changed.
- `year` (integer, required): Billing year in which the change was found.
- `articleId` (string (uuid)): The masterdata article.
- `currency` (string): Currency (ISO 4217).
- `decidedAt` (string (date-time)): When it was accepted or rejected.
- `decidedBy` (string): Who decided; missing while open.
- `newPurchase` (number): Suggested purchase price.
- `newSales` (number): Suggested sales price.
- `oldPurchase` (number): Purchase price now in masterdata.
- `oldSales` (number): Sales price now in masterdata.
- `priceSince` (string (date-time)): The new price applies since.
- `subscriptionId` (string): The subscription the price was read from.
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.

Example 200 answer:

```json
{
  "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7f21",
  "articleNumber": "MSFTCFQ7TTC0LCHC0002P1YM",
  "currency": "EUR",
  "decidedAt": "2026-11-19T10:30:00Z",
  "decidedBy": "laura.kaestner@muster-it.example",
  "id": "6e7f8a9b-0c1d-4e2f-8a3b-4c5d6e7f8a01",
  "month": 10,
  "newPurchase": 18,
  "newSales": 21.6,
  "oldPurchase": 17.2,
  "oldSales": 20.6,
  "priceSince": "2026-11-01T00:00:00Z",
  "provider": "ingram",
  "skuKey": "CFQ7TTC0LCHC:0002/P1YM",
  "status": "accepted",
  "subscriptionId": "1700012399",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10",
  "updatedAt": "2026-11-19T10:30:00Z",
  "year": 2026
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/price-suggestions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/accept' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Reject a price suggestion (tenant:trade:msp:write, tenant:trade:msp:approve or tenant:masterdata:write)

`POST /api/trade/v1/msp/price-suggestions/{id}/reject`

Module: Trade · operationId: `rejectMspPriceSuggestion` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Marks the suggestion rejected; masterdata is not changed.
Needs any one of `tenant:trade:msp:write`, `tenant:trade:msp:approve`, `tenant:masterdata:write`. A suggestion is decided once: a second decision answers 409 `price_suggestion_decided`; one a run changed since it was read answers 409 `price_suggestion_changed`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The decided suggestion (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** Already decided (`price_suggestion_decided`), changed by a run since it was read (`price_suggestion_changed`) or – accept only – the article has other prices in masterdata by now (`price_changed`, nothing written) (`application/json`)

Fields of the 200 answer:

- `articleNumber` (string, required): Article number in masterdata.
- `id` (string (uuid), required): Id of the suggestion.
- `month` (integer, required): Billing month in which the change was found.
- `provider` (string, required): The provider the price comes from.
- `skuKey` (string, required): The provider's SKU key of the article.
- `status` (string, required): Status of the suggestion (`open`, `accepted`, `rejected`). (one of `open`, `accepted`, `rejected`)
- `updatedAt` (string (date-time), required): When the suggestion last changed.
- `year` (integer, required): Billing year in which the change was found.
- `articleId` (string (uuid)): The masterdata article.
- `currency` (string): Currency (ISO 4217).
- `decidedAt` (string (date-time)): When it was accepted or rejected.
- `decidedBy` (string): Who decided; missing while open.
- `newPurchase` (number): Suggested purchase price.
- `newSales` (number): Suggested sales price.
- `oldPurchase` (number): Purchase price now in masterdata.
- `oldSales` (number): Sales price now in masterdata.
- `priceSince` (string (date-time)): The new price applies since.
- `subscriptionId` (string): The subscription the price was read from.
- `supplierAddressId` (string (uuid)): Masterdata address of the supplier.

Example 200 answer:

```json
{
  "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7f21",
  "articleNumber": "MSFTCFQ7TTC0LCHC0002P1YM",
  "currency": "EUR",
  "decidedAt": "2026-11-19T10:30:00Z",
  "decidedBy": "laura.kaestner@muster-it.example",
  "id": "6e7f8a9b-0c1d-4e2f-8a3b-4c5d6e7f8a01",
  "month": 10,
  "newPurchase": 18,
  "newSales": 21.6,
  "oldPurchase": 17.2,
  "oldSales": 20.6,
  "priceSince": "2026-11-01T00:00:00Z",
  "provider": "ingram",
  "skuKey": "CFQ7TTC0LCHC:0002/P1YM",
  "status": "rejected",
  "subscriptionId": "1700012399",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10",
  "updatedAt": "2026-11-19T10:30:00Z",
  "year": 2026
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/price-suggestions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/reject' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the usage runs of a month (tenant:trade:msp:read)

`GET /api/trade/v1/msp/runs`

Module: Trade · operationId: `listMspRuns` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

One run per provider and month with its state, item count, progress while it runs and the file names of its stored raw answers (`rawAnswers`), plus the active providers.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |

### Responses

- **200** Runs (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `month` (integer)
- `providers` (array of string): The active providers a collection runs, in their order – also those without a run of the month yet (each can be collected alone with `providers` of `collectMspUsage`); empty while MSP billing is off.
- `runs` (array of MspRun)
  - `attempts` (integer): Failures in a row; the scheduler takes a failed run again at `nextAttemptAt`.
  - `error` (string): Why the run failed.
  - `finishedAt` (string (date-time)): When it finished; absent while running.
  - `id` (string (uuid)): Id of the run.
  - `itemCount` (integer): Number of usage items collected.
  - `month` (integer): Month (1–12) of the billing month.
  - `nextAttemptAt` (string (date-time)): When the scheduler retries a failed run; missing otherwise.
  - `progressDone` (integer): How far a running run is: Ingram subscription details read, Sophos pages read. Missing while unknown; a new claim clears it.
  - `progressTotal` (integer): Of how many `progressDone` counts (Ingram subscriptions, Sophos pages). Missing while unknown or when the provider cannot tell.
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `rawAnswers` (array of string): File names of the run's raw provider answers, stored in the database; `getMspRawAnswer` downloads one.
  - `startedAt` (string (date-time)): When it started.
  - `status` (string): Status of the run (`running`, `succeeded`, `failed`). (one of `running`, `succeeded`, `failed`)
  - `triggeredBy` (string): `schedule` or the person who collected.
  - `year` (integer): Year of the billing month.
- `year` (integer)

Example 200 answer:

```json
{
  "month": 10,
  "providers": [
    "mailstore",
    "sophos",
    "ingram",
    "itc",
    "itc-backup",
    "itc-licenses"
  ],
  "runs": [
    {
      "attempts": 0,
      "finishedAt": "2026-11-01T05:00:12Z",
      "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f01",
      "itemCount": 9,
      "month": 10,
      "provider": "mailstore",
      "rawAnswers": [
        "instances.json"
      ],
      "startedAt": "2026-11-01T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule",
      "year": 2026
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-02T05:01:05Z",
      "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f02",
      "itemCount": 41,
      "month": 10,
      "progressDone": 2,
      "progressTotal": 2,
      "provider": "sophos",
      "rawAnswers": [
        "usage-page-1.json",
        "usage-page-2.json"
      ],
      "startedAt": "2026-11-02T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule",
      "year": 2026
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-01T05:04:31Z",
      "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
      "itemCount": 164,
      "month": 10,
      "progressDone": 160,
      "progressTotal": 160,
      "provider": "ingram",
      "rawAnswers": [
        "subscriptions-search.json",
        "subscriptions-details.json"
      ],
      "startedAt": "2026-11-01T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule",
      "year": 2026
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-03T06:10:02Z",
      "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f04",
      "itemCount": 6,
      "month": 10,
      "provider": "itc",
      "rawAnswers": [
        "vm-report-2026-10.csv"
      ],
      "startedAt": "2026-11-03T06:10:00Z",
      "status": "succeeded",
      "triggeredBy": "anna.weber@muster-it.example",
      "year": 2026
    }
  ],
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/runs' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Download every raw provider answer of a run as a ZIP file (tenant:trade:msp:read)

`GET /api/trade/v1/msp/runs/{id}/answers`

Module: Trade · operationId: `downloadMspRawAnswers` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

One file per entry of the run's `rawAnswers`, named like it; the attachment is named `<provider>-<yyyy>-<mm>-antworten.zip`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** ZIP file of the stored answers (`application/zip`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/runs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/answers' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the subscriptions a run read (tenant:trade:msp:read)

`GET /api/trade/v1/msp/runs/{id}/subscriptions`

Module: Trade · operationId: `listMspRunSubscriptions` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Read from the run's stored answers, in their order, with the number of usage items the run made of each: for Ingram the subscriptions of the search answers, for Sophos one entry per customer account of the usage rows, for MailStore one per instance (the id is the usage items' `sourceCustomer`). Runs of other providers are not found.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Subscriptions (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `month` (integer): Month (1–12) of the billing month.
- `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
- `runId` (string (uuid)): Id of the usage run.
- `subscriptions` (array of MspRunSubscriptionRow): Subscriptions the run read.
  - `billingPeriod` (integer): Length of the billing period.
  - `billingPeriodUnit` (string): Unit of the billing period.
  - `endCustomer` (string): End customer of the subscription.
  - `endCustomerId` (string): Ingram end customer id; for Sophos and MailStore the customer number hint.
  - `hasDetails` (boolean): The run stored the answer of the subscription's details call (Ingram; always true for the other providers).
  - `isTrial` (boolean): The subscription is a trial.
  - `items` (integer): Usage items the run made of the subscription.
  - `nextBillingDate` (string): Ingram next billing date, same format and source as `startDate`; omitted when unknown.
  - `planName` (string): Ingram plan; for Sophos the product descriptions of the account's rows, for MailStore `MailStore SPE`.
  - `quantity` (number): Quantity.
  - `startDate` (string): Ingram start date as Ingram sends it (`2026-11-15` or `2022-11-11T00:00:00`), from the details answer, else the search entry; omitted when unknown.
  - `status` (string): Status at the provider.
  - `subscriptionId` (string): Ingram subscription id; for Sophos and MailStore the provider customer (`sourceCustomer` of the usage items).
- `year` (integer): Year of the billing month.

Example 200 answer:

```json
{
  "month": 10,
  "provider": "ingram",
  "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
  "subscriptions": [
    {
      "billingPeriod": 1,
      "billingPeriodUnit": "MONTHS",
      "endCustomer": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "endCustomerId": "1100430325",
      "hasDetails": true,
      "isTrial": false,
      "items": 1,
      "nextBillingDate": "2026-11-11",
      "planName": "Microsoft 365 Business Standard",
      "quantity": 12,
      "startDate": "2025-11-11T00:00:00",
      "status": "ACTIVE",
      "subscriptionId": "1700012345"
    }
  ],
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/runs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/subscriptions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get everything a run stored of one subscription (tenant:trade:msp:read)

`GET /api/trade/v1/msp/runs/{id}/subscriptions/{subscriptionId}`

Module: Trade · operationId: `getMspRunSubscription` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `subscriptionId` | path | string | yes | Ingram subscription id; for Sophos and MailStore the provider customer (`sourceCustomer`). |

### Responses

- **200** The subscription (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid)): The masterdata address the subscription's usage is billed to (customer mapping or contract); omitted while it has none.
- `addressName` (string): The name of that address as the mapping or contract keeps it
- `details` (object): The answer of `GET /resellers/v7/subscriptions/{id}` as Ingram sent it; missing when the run did not read it.
- `items` (array of MspUsageItem): Usage items of the subscription.
  - `customerHint` (string): Customer number the provider keeps (MailStore instance, Ingram custom account id, Sophos: the number of assignedAccountIdentifier `<number> | <name>`).
  - `id` (string (uuid)): Id of the usage item.
  - `month` (integer): Month (1–12) of the billing month.
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `quantity` (number): Quantity used in the month.
  - `runId` (string (uuid)): Id of the usage run.
  - `sourceCustomer` (string): The provider's id of its customer (mapping key).
  - `sourceCustomerName` (string): The provider's name of its customer (Sophos: the name of assignedAccountIdentifier `<number> | <name>`).
  - `sourceName` (string): The provider's product name.
  - `sourceRef` (string): The provider's subscription reference.
  - `sourceSku` (string): The provider's SKU.
  - `year` (integer): Year of the billing month.
- `month` (integer): Month (1–12) of the billing month.
- `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
- `quantities` (array of object): Ingram: the subscription's billed quantity of every month a run collected it (sum of its usage items), oldest first – the quantity over time; Ingram's order history has amounts only. Missing without any.
  - `month` (integer, required): Month (1–12) of the billing month.
  - `quantity` (number, required): Quantity of the month.
  - `year` (integer, required): Year of the billing month.
- `records` (array of object): Sophos and MailStore: the records of the answers as the provider sent them – the customer's usage rows (also those without billable quantity), the MailStore instance.
- `runId` (string (uuid)): Id of the usage run.
- `subscriptionId` (string): The provider's subscription id.
- `summary` (object): The subscription's entry of the search answer (`GET /resellers/v7/subscriptions/search`) as Ingram sent it.
- `year` (integer): Year of the billing month.

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "details": {
    "billingPeriod": 1,
    "billingPeriodUnit": "MONTHS",
    "nextBillingDate": "2026-11-11",
    "resources": [
      {
        "name": "Microsoft 365 Business Standard",
        "quantity": 12,
        "unitCost": 10.4,
        "unitPrice": 12.5,
        "vendorPartNumber": "CFQ7TTC0LDPB:0001"
      }
    ],
    "startDate": "2025-11-11T00:00:00",
    "status": "ACTIVE",
    "subscriptionId": "1700012345"
  },
  "items": [
    {
      "customerHint": "20002",
      "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01",
      "month": 10,
      "provider": "ingram",
      "quantity": 12,
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
      "sourceCustomer": "1100430325",
      "sourceCustomerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "sourceName": "Microsoft 365 Business Standard",
      "sourceRef": "1700012345",
      "sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
      "year": 2026
    }
  ],
  "month": 10,
  "provider": "ingram",
  "quantities": [
    {
      "month": 8,
      "quantity": 10,
      "year": 2026
    },
    {
      "month": 9,
      "quantity": 12,
      "year": 2026
    },
    {
      "month": 10,
      "quantity": 12,
      "year": 2026
    }
  ],
  "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
  "subscriptionId": "1700012345",
  "summary": {
    "endCustomerId": "1100430325",
    "endCustomerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
    "quantity": 12,
    "status": "ACTIVE",
    "subscriptionId": "1700012345",
    "subscriptionName": "Microsoft 365 Business Standard"
  },
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/runs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/subscriptions/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the subscriptions the runs of a month read (tenant:trade:msp:read)

`GET /api/trade/v1/msp/subscriptions`

Module: Trade · operationId: `listMspMonthSubscriptions` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Lists what each succeeded run of the month read (one run per provider and month), in provider order, with the number of usage items the run made of each subscription. Failed and running runs and providers without a subscription view are left out. `due` tells whether the month `dueMonth` (default `month`) bills the subscription: it needs usage items and is no trial; Sophos and MailStore customers and monthly Ingram subscriptions are due every month; longer Ingram billing periods in the month of the next billing date and a whole number of periods before or after it (without a next billing date: after the start date); without a date the subscription counts as due. The month's MSP drafts bill only the usage of the subscriptions due in it; the others stay assigned but go on no invoice.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |
| `dueMonth` | query | string |  | Month `YYYY-MM` for which `due` is evaluated; default the month of the runs (`month`). Malformed answers `400`. |

### Responses

- **200** Subscriptions (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `dueMonth` (integer): Month `due` is evaluated for (`dueMonth` parameter, default `month`).
- `dueYear` (integer): Year `due` is evaluated for.
- `month` (integer): Month (1–12) of the billing month.
- `subscriptions` (array of MspMonthSubscriptionRow): Subscriptions the runs of the month read.
- `year` (integer): Year of the billing month.

Example 200 answer:

```json
{
  "dueMonth": 10,
  "dueYear": 2026,
  "month": 10,
  "subscriptions": [
    {
      "billingPeriod": 1,
      "billingPeriodUnit": "MONTHS",
      "due": true,
      "endCustomer": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "endCustomerId": "1100430325",
      "hasDetails": true,
      "isTrial": false,
      "items": 1,
      "nextBillingDate": "2026-11-11",
      "planName": "Microsoft 365 Business Standard",
      "provider": "ingram",
      "quantity": 12,
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
      "startDate": "2025-11-11T00:00:00",
      "status": "ACTIVE",
      "subscriptionId": "1700012345"
    },
    {
      "billingPeriod": 1,
      "billingPeriodUnit": "YEARS",
      "due": false,
      "endCustomer": "Donau Maschinenbau AG",
      "endCustomerId": "1100430411",
      "hasDetails": true,
      "isTrial": false,
      "items": 1,
      "nextBillingDate": "2027-02-28",
      "planName": "Windows Server 2025 Standard ESU",
      "provider": "ingram",
      "quantity": 2,
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
      "startDate": "2026-02-28T00:00:00",
      "status": "ACTIVE",
      "subscriptionId": "1700012377"
    }
  ],
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/subscriptions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Download a raw provider answer of a run (tenant:trade:msp:read)

`GET /api/trade/v1/msp/runs/{id}/answers/{name}`

Module: Trade · operationId: `getMspRawAnswer` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `name` | path | string | yes | One of the run's `rawAnswers`. |

### Responses

- **200** The stored answer as JSON (an answer that was not JSON is a JSON string), sent as an attachment named like the answer (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

Example 200 answer:

```json
{
  "pageNumber": 1,
  "pageSize": 100,
  "recordsFound": 160,
  "subscriptions": [
    {
      "endCustomerId": "1100430325",
      "endCustomerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "quantity": 12,
      "status": "ACTIVE",
      "subscriptionId": "1700012345",
      "subscriptionName": "Microsoft 365 Business Standard"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/runs/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/answers/string' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the collected usage of a month (tenant:trade:msp:read)

`GET /api/trade/v1/msp/usage`

Module: Trade · operationId: `listMspUsage` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |
| `provider` | query | string |  | (one of `mailstore`, `sophos`, `ingram`, `itc`, `itc-backup`, `itc-licenses`) |
| `addressId` | query | string (uuid) |  | Only the items billed to this masterdata address (mapping or contract) – a customer's usage of all providers |

### Responses

- **200** Usage items (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `items` (array of MspUsageLine)
- `month` (integer)
- `year` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
      "addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "customerHint": "20002",
      "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01",
      "month": 10,
      "provider": "ingram",
      "quantity": 12,
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
      "sourceCustomer": "1100430325",
      "sourceCustomerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "sourceName": "Microsoft 365 Business Standard",
      "sourceRef": "1700012345",
      "sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
      "year": 2026
    },
    {
      "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c21",
      "missing": [
        "customer"
      ],
      "month": 10,
      "provider": "sophos",
      "quantity": 9,
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f02",
      "sourceCustomer": "6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0",
      "sourceCustomerName": "Bäckerei Sonnleitner GmbH",
      "sourceName": "Sophos Intercept X Advanced",
      "sourceRef": "6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0",
      "sourceSku": "CIXA0UDAC",
      "year": 2026
    }
  ],
  "month": 10,
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/usage' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the usage no customer is assigned to (tenant:trade:msp:read)

`GET /api/trade/v1/msp/unassigned`

Module: Trade · operationId: `listMspUnassignedUsage` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

The clarification list: usage items whose provider customer neither a customer mapping nor a contract
(`cspSubscriptionId` = the item's reference, `cspTenantId` = the provider customer) assigns, and problems that
concern no invoice (e.g. a contract without customer). Computed on request; nothing is stored.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |

### Responses

- **200** Unassigned usage (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `items` (array of MspUsageItem)
  - `customerHint` (string): Customer number the provider keeps (MailStore instance, Ingram custom account id, Sophos: the number of assignedAccountIdentifier `<number> | <name>`).
  - `id` (string (uuid)): Id of the usage item.
  - `month` (integer): Month (1–12) of the billing month.
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `quantity` (number): Quantity used in the month.
  - `runId` (string (uuid)): Id of the usage run.
  - `sourceCustomer` (string): The provider's id of its customer (mapping key).
  - `sourceCustomerName` (string): The provider's name of its customer (Sophos: the name of assignedAccountIdentifier `<number> | <name>`).
  - `sourceName` (string): The provider's product name.
  - `sourceRef` (string): The provider's subscription reference.
  - `sourceSku` (string): The provider's SKU.
  - `year` (integer): Year of the billing month.
- `month` (integer)
- `problems` (array of string)
- `year` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c21",
      "month": 10,
      "provider": "sophos",
      "quantity": 9,
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f02",
      "sourceCustomer": "6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0",
      "sourceCustomerName": "Bäckerei Sonnleitner GmbH",
      "sourceName": "Sophos Intercept X Advanced",
      "sourceRef": "6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0",
      "sourceSku": "CIXA0UDAC",
      "year": 2026
    }
  ],
  "month": 10,
  "problems": [],
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/unassigned' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the MSP invoices of a month (tenant:trade:msp:read)

`GET /api/trade/v1/msp/invoices`

Module: Trade · operationId: `listMspInvoices` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

One invoice per billed customer address and month, without lines.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |

### Responses

- **200** Invoices (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `invoices` (array of MspInvoice)
  - `addressId` (string (uuid)): Masterdata address of the customer.
  - `addressName` (string): Name of the customer.
  - `approvedAt` (string (date-time)): When the invoice was approved.
  - `approvedBy` (string): Who approved the invoice.
  - `attempts` (integer): Number of posting attempts.
  - `computedAt` (string (date-time)): When the draft was computed.
  - `delivery` (MspDelivery): `send`: approving issues the invoice in Verkauf and mails it to the customer; `issue`: it is only issued (final number, XRechnung, the XML in DMS). (one of `send`, `issue`)
  - `error` (string): Why the last posting failed.
  - `id` (string (uuid)): Id of the MSP invoice.
  - `lines` (array of MspInvoiceLine): Positions of the invoice.
    - `articleNumber` (string): Article number in masterdata.
    - `contractId` (string (uuid)): Contract of the position.
    - `contractItemId` (string (uuid)): The contract position of a `fixed` line.
    - `kind` (string): `fixed` (a contract item) or `usage` (collected usage). (one of `fixed`, `usage`)
    - `name` (string): Name printed on the invoice position.
    - `position` (integer): Position number of the line.
    - `problem` (string): Why the position cannot be billed as it is.
    - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
    - `quantity` (number): Quantity.
    - `sourceSku` (string): The provider's SKU.
    - `text` (string): Printed below the name; missing when none. ITC: `VM: <name>` of the virtual machine.
    - `total` (number): Net total of the position.
    - `unitPrice` (number): Missing when no price is known (a problem).
    - `usageItemIds` (array of string (uuid)): The usage items of a `usage` line.
  - `month` (integer): Month (1–12) of the billing month.
  - `netTotal` (number): Net total of the invoice.
  - `postedAt` (string (date-time)): When the invoice was posted.
  - `problems` (array of string): Each blocks the approval (e.g. "Preisänderung für Artikel … wartet auf Freigabe (… → … €)." while a price suggestion of a billed article is open).
  - `stale` (boolean): Usage, a mapping or a contract position changed after the computation: recompute before approving.
  - `status` (string): Status of the MSP invoice (`draft`, `approved`, `posting`, `posted`, `failed`). (one of `draft`, `approved`, `posting`, `posted`, `failed`)
  - `transactionId` (string (uuid)): The booked INVOICE in trade.
  - `transactionNumber` (string): Number of the invoice in Verkauf once posted.
  - `year` (integer): Year of the billing month.
- `month` (integer)
- `year` (integer)

Example 200 answer:

```json
{
  "invoices": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
      "addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "attempts": 0,
      "computedAt": "2026-11-03T06:12:00Z",
      "delivery": "send",
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
      "lines": [
        {
          "articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
          "kind": "usage",
          "name": "Microsoft 365 Business Standard 1YM",
          "position": 1,
          "provider": "ingram",
          "quantity": 12,
          "sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
          "total": 150,
          "unitPrice": 12.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01"
          ]
        },
        {
          "articleNumber": "ITC7030222P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server CPU Performance Plus",
          "position": 2,
          "provider": "itc",
          "quantity": 4,
          "sourceSku": "7030222",
          "text": "VM: kanzlei-srv01",
          "total": 38,
          "unitPrice": 9.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c11"
          ]
        },
        {
          "articleNumber": "ITC7030220P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server RAM 1 GB",
          "position": 3,
          "provider": "itc",
          "quantity": 16,
          "sourceSku": "7030220",
          "text": "VM: kanzlei-srv01",
          "total": 51.2,
          "unitPrice": 3.2,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c12"
          ]
        },
        {
          "articleNumber": "ITC7030003P1MM",
          "kind": "usage",
          "name": "ITC CLOUD 3 Wege Storage Standard je GB",
          "position": 4,
          "provider": "itc",
          "quantity": 500,
          "sourceSku": "7030003",
          "text": "VM: kanzlei-srv01",
          "total": 60,
          "unitPrice": 0.12,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c13"
          ]
        },
        {
          "articleNumber": "DL-9005",
          "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
          "contractItemId": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
          "kind": "fixed",
          "name": "Supportpauschale Fernwartung, monatlich",
          "position": 5,
          "quantity": 1,
          "total": 180,
          "unitPrice": 180
        }
      ],
      "month": 10,
      "netTotal": 479.2,
      "problems": [],
      "stale": false,
      "status": "draft",
      "year": 2026
    },
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
      "addressName": "Donau Maschinenbau AG",
      "attempts": 0,
      "computedAt": "2026-11-03T06:12:00Z",
      "delivery": "send",
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02",
      "lines": [
        {
          "articleNumber": "ITC7030222P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server CPU Performance Plus",
          "position": 1,
          "provider": "itc",
          "quantity": 8,
          "sourceSku": "7030222",
          "text": "VM: dmb-erp01",
          "total": 76,
          "unitPrice": 9.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c14"
          ]
        },
        {
          "articleNumber": "ITC7030220P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server RAM 1 GB",
          "position": 2,
          "provider": "itc",
          "quantity": 32,
          "sourceSku": "7030220",
          "text": "VM: dmb-erp01",
          "total": 102.4,
          "unitPrice": 3.2,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c15"
          ]
        },
        {
          "articleNumber": "ITC7030003P1MM",
          "kind": "usage",
          "name": "ITC CLOUD 3 Wege Storage Standard je GB",
          "position": 3,
          "provider": "itc",
          "quantity": 1200,
          "sourceSku": "7030003",
          "text": "VM: dmb-erp01",
          "total": 144,
          "unitPrice": 0.12,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c16"
          ]
        }
      ],
      "month": 10,
      "netTotal": 322.4,
      "problems": [],
      "stale": false,
      "status": "draft",
      "year": 2026
    }
  ],
  "month": 10,
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/invoices' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get the state of a billing month (tenant:trade:msp:read)

`GET /api/trade/v1/msp/overview`

Module: Trade · operationId: `getMspOverview` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

The active connectors with their planned collection and run, whether the month is complete (every active
connector collected it; only then may invoices be approved), the subscriptions still missing a customer or an
article, the invoice counts and the automatic billing window. `month` defaults to the month the scheduler
bills now.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |

### Responses

- **200** Overview (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `autoBilling` (object): The automatic billing window of the month.
  - `enabled` (boolean): Automatic billing is on.
  - `from` (string (date-time)): Start of the automatic billing window of the month.
  - `to` (string (date-time)): End of the automatic billing window of the month.
- `blockers` (array of string): German texts naming what keeps the automatic billing from approving the drafts (e.g. "<n> Preisänderung(en) warten auf Freigabe.": open price suggestions, `listMspPriceSuggestions`); empty: nothing.
- `complete` (boolean): Every active connector has collected the month; only then may invoices be approved.
- `connectors` (array of object): The active connectors in their order.
  - `attempts` (integer): Number of attempts of the run.
  - `error` (string): Why the last run failed.
  - `finishedAt` (string (date-time)): When it finished; absent while running.
  - `itemCount` (integer): Number of usage items collected.
  - `nextAttemptAt` (string (date-time)): When the scheduler tries again.
  - `plannedAt` (string (date-time)): Scheduled collection of the month (in the month after it).
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `runId` (string (uuid)): Id of the usage run.
  - `startedAt` (string (date-time)): When it started.
  - `status` (string): Status of the run of the month. (one of `planned`, `running`, `succeeded`, `failed`)
  - `triggeredBy` (string): `schedule` or the person who collected.
  - `upload` (boolean): The connector's reports are uploaded (`uploadMspItcReport`, ITC Riemer), not collected; `plannedAt` is then zero (`0001-01-01T00:00:00Z`). Missing otherwise.
- `enabled` (boolean): At least one MSP connector is enabled.
- `invoices` (object): Number of MSP invoices of the month per status.
  - `approved` (integer): Number of approved invoices.
  - `drafts` (integer): Number of drafts.
  - `draftsBlocked` (integer): Drafts with problems or still stale.
  - `failed` (integer): Number of failed invoices.
  - `posted` (integer): Number of posted invoices.
- `missingArticle` (integer): Subscriptions (usage items) of the month without an article.
- `missingCustomer` (integer): Subscriptions (usage items) of the month without a customer.
- `month` (integer): Month (1–12) of the billing month.
- `year` (integer): Year of the billing month.

Example 200 answer:

```json
{
  "autoBilling": {
    "enabled": true,
    "from": "2026-11-05T05:00:00Z",
    "to": "2026-11-10T16:00:00Z"
  },
  "blockers": [
    "1 Abonnement ohne Kunde (Zuordnungen).",
    "1 Preisänderung(en) warten auf Freigabe."
  ],
  "complete": true,
  "connectors": [
    {
      "attempts": 0,
      "finishedAt": "2026-11-01T05:00:12Z",
      "itemCount": 9,
      "plannedAt": "2026-11-01T05:00:00Z",
      "provider": "mailstore",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f01",
      "startedAt": "2026-11-01T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule"
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-02T05:01:05Z",
      "itemCount": 41,
      "plannedAt": "2026-11-02T05:00:00Z",
      "provider": "sophos",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f02",
      "startedAt": "2026-11-02T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule"
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-01T05:04:31Z",
      "itemCount": 164,
      "plannedAt": "2026-11-01T05:00:00Z",
      "provider": "ingram",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
      "startedAt": "2026-11-01T05:00:00Z",
      "status": "succeeded",
      "triggeredBy": "schedule"
    },
    {
      "attempts": 0,
      "finishedAt": "2026-11-03T06:10:02Z",
      "itemCount": 6,
      "plannedAt": "0001-01-01T00:00:00Z",
      "provider": "itc",
      "runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f04",
      "startedAt": "2026-11-03T06:10:00Z",
      "status": "succeeded",
      "triggeredBy": "anna.weber@muster-it.example",
      "upload": true
    }
  ],
  "enabled": true,
  "invoices": {
    "approved": 0,
    "drafts": 14,
    "draftsBlocked": 1,
    "failed": 0,
    "posted": 0
  },
  "missingArticle": 0,
  "missingCustomer": 1,
  "month": 10,
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/overview' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Set the delivery of MSP invoices (tenant:trade:msp:approve)

`PUT /api/trade/v1/msp/invoices/delivery`

Module: Trade · operationId: `setMspInvoiceDelivery` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`) · **Deprecated**

Sets whether approving the invoices mails them (`send`) or only issues them (`issue`). Invoices that are
already booked keep their delivery. Deprecated: approving takes the delivery itself
(`POST /api/trade/v1/msp/invoices/{id}/approve` with `delivery`); the portal no longer sets it beforehand.

### Request body

`application/json` (required)

- `delivery` (MspDelivery, required): `send`: approving issues the invoice in Verkauf and mails it to the customer; `issue`: it is only issued (final number, XRechnung, the XML in DMS). (one of `send`, `issue`)
- `ids` (array of string (uuid), required)

Example:

```json
{
  "delivery": "issue",
  "ids": [
    "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
    "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02"
  ]
}
```

### Responses

- **200** Number of invoices changed (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `updated` (integer, required)

Example 200 answer:

```json
{
  "updated": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/msp/invoices/delivery' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"delivery":"issue","ids":["2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01","2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02"]}'
```

## Compute the drafts of a month (tenant:trade:msp:approve)

`POST /api/trade/v1/msp/invoices/recompute`

Module: Trade · operationId: `recomputeMspInvoices` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Builds one draft per customer address from the contract items due in the month and the assigned usage, priced
by the article mapping, else the contract's usage item, else the masterdata article. Usage of Ingram
subscriptions the month does not bill (`due: false` in `listMspMonthSubscriptions`) is left out. The tenant's own
masterdata address (customer number = the tenant's customer number) gets no draft. Lines without article or
price are problems that block the approval. Invoices past draft are kept; drafts of customers without
positions are removed.

### Request body

`application/json`

- `month` (integer): (max 12)
- `year` (integer)

Example:

```json
{
  "month": 10,
  "year": 2026
}
```

### Responses

- **200** The invoices of the month after the computation (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `invoices` (array of MspInvoice)
  - `addressId` (string (uuid)): Masterdata address of the customer.
  - `addressName` (string): Name of the customer.
  - `approvedAt` (string (date-time)): When the invoice was approved.
  - `approvedBy` (string): Who approved the invoice.
  - `attempts` (integer): Number of posting attempts.
  - `computedAt` (string (date-time)): When the draft was computed.
  - `delivery` (MspDelivery): `send`: approving issues the invoice in Verkauf and mails it to the customer; `issue`: it is only issued (final number, XRechnung, the XML in DMS). (one of `send`, `issue`)
  - `error` (string): Why the last posting failed.
  - `id` (string (uuid)): Id of the MSP invoice.
  - `lines` (array of MspInvoiceLine): Positions of the invoice.
    - `articleNumber` (string): Article number in masterdata.
    - `contractId` (string (uuid)): Contract of the position.
    - `contractItemId` (string (uuid)): The contract position of a `fixed` line.
    - `kind` (string): `fixed` (a contract item) or `usage` (collected usage). (one of `fixed`, `usage`)
    - `name` (string): Name printed on the invoice position.
    - `position` (integer): Position number of the line.
    - `problem` (string): Why the position cannot be billed as it is.
    - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
    - `quantity` (number): Quantity.
    - `sourceSku` (string): The provider's SKU.
    - `text` (string): Printed below the name; missing when none. ITC: `VM: <name>` of the virtual machine.
    - `total` (number): Net total of the position.
    - `unitPrice` (number): Missing when no price is known (a problem).
    - `usageItemIds` (array of string (uuid)): The usage items of a `usage` line.
  - `month` (integer): Month (1–12) of the billing month.
  - `netTotal` (number): Net total of the invoice.
  - `postedAt` (string (date-time)): When the invoice was posted.
  - `problems` (array of string): Each blocks the approval (e.g. "Preisänderung für Artikel … wartet auf Freigabe (… → … €)." while a price suggestion of a billed article is open).
  - `stale` (boolean): Usage, a mapping or a contract position changed after the computation: recompute before approving.
  - `status` (string): Status of the MSP invoice (`draft`, `approved`, `posting`, `posted`, `failed`). (one of `draft`, `approved`, `posting`, `posted`, `failed`)
  - `transactionId` (string (uuid)): The booked INVOICE in trade.
  - `transactionNumber` (string): Number of the invoice in Verkauf once posted.
  - `year` (integer): Year of the billing month.
- `month` (integer)
- `problems` (array of string)
- `unassigned` (integer): Number of usage items without customer (`listMspUnassignedUsage`).
- `year` (integer)

Example 200 answer:

```json
{
  "invoices": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
      "addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "attempts": 0,
      "computedAt": "2026-11-03T06:12:00Z",
      "delivery": "send",
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
      "lines": [
        {
          "articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
          "kind": "usage",
          "name": "Microsoft 365 Business Standard 1YM",
          "position": 1,
          "provider": "ingram",
          "quantity": 12,
          "sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
          "total": 150,
          "unitPrice": 12.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01"
          ]
        },
        {
          "articleNumber": "ITC7030222P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server CPU Performance Plus",
          "position": 2,
          "provider": "itc",
          "quantity": 4,
          "sourceSku": "7030222",
          "text": "VM: kanzlei-srv01",
          "total": 38,
          "unitPrice": 9.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c11"
          ]
        },
        {
          "articleNumber": "ITC7030220P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server RAM 1 GB",
          "position": 3,
          "provider": "itc",
          "quantity": 16,
          "sourceSku": "7030220",
          "text": "VM: kanzlei-srv01",
          "total": 51.2,
          "unitPrice": 3.2,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c12"
          ]
        },
        {
          "articleNumber": "ITC7030003P1MM",
          "kind": "usage",
          "name": "ITC CLOUD 3 Wege Storage Standard je GB",
          "position": 4,
          "provider": "itc",
          "quantity": 500,
          "sourceSku": "7030003",
          "text": "VM: kanzlei-srv01",
          "total": 60,
          "unitPrice": 0.12,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c13"
          ]
        },
        {
          "articleNumber": "DL-9005",
          "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
          "contractItemId": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
          "kind": "fixed",
          "name": "Supportpauschale Fernwartung, monatlich",
          "position": 5,
          "quantity": 1,
          "total": 180,
          "unitPrice": 180
        }
      ],
      "month": 10,
      "netTotal": 479.2,
      "problems": [],
      "stale": false,
      "status": "draft",
      "year": 2026
    },
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
      "addressName": "Donau Maschinenbau AG",
      "attempts": 0,
      "computedAt": "2026-11-03T06:12:00Z",
      "delivery": "send",
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02",
      "lines": [
        {
          "articleNumber": "ITC7030222P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server CPU Performance Plus",
          "position": 1,
          "provider": "itc",
          "quantity": 8,
          "sourceSku": "7030222",
          "text": "VM: dmb-erp01",
          "total": 76,
          "unitPrice": 9.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c14"
          ]
        },
        {
          "articleNumber": "ITC7030220P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server RAM 1 GB",
          "position": 2,
          "provider": "itc",
          "quantity": 32,
          "sourceSku": "7030220",
          "text": "VM: dmb-erp01",
          "total": 102.4,
          "unitPrice": 3.2,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c15"
          ]
        },
        {
          "articleNumber": "ITC7030003P1MM",
          "kind": "usage",
          "name": "ITC CLOUD 3 Wege Storage Standard je GB",
          "position": 3,
          "provider": "itc",
          "quantity": 1200,
          "sourceSku": "7030003",
          "text": "VM: dmb-erp01",
          "total": 144,
          "unitPrice": 0.12,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c16"
          ]
        }
      ],
      "month": 10,
      "netTotal": 322.4,
      "problems": [],
      "stale": false,
      "status": "draft",
      "year": 2026
    }
  ],
  "month": 10,
  "problems": [],
  "unassigned": 1,
  "year": 2026
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/invoices/recompute' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"month":10,"year":2026}'
```

## Get an MSP invoice with its lines (tenant:trade:msp:read)

`GET /api/trade/v1/msp/invoices/{id}`

Module: Trade · operationId: `getMspInvoice` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Invoice (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid)): Masterdata address of the customer.
- `addressName` (string): Name of the customer.
- `approvedAt` (string (date-time)): When the invoice was approved.
- `approvedBy` (string): Who approved the invoice.
- `attempts` (integer): Number of posting attempts.
- `computedAt` (string (date-time)): When the draft was computed.
- `delivery` (MspDelivery): `send`: approving issues the invoice in Verkauf and mails it to the customer; `issue`: it is only issued (final number, XRechnung, the XML in DMS). (one of `send`, `issue`)
- `error` (string): Why the last posting failed.
- `id` (string (uuid)): Id of the MSP invoice.
- `lines` (array of MspInvoiceLine): Positions of the invoice.
  - `articleNumber` (string): Article number in masterdata.
  - `contractId` (string (uuid)): Contract of the position.
  - `contractItemId` (string (uuid)): The contract position of a `fixed` line.
  - `kind` (string): `fixed` (a contract item) or `usage` (collected usage). (one of `fixed`, `usage`)
  - `name` (string): Name printed on the invoice position.
  - `position` (integer): Position number of the line.
  - `problem` (string): Why the position cannot be billed as it is.
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `quantity` (number): Quantity.
  - `sourceSku` (string): The provider's SKU.
  - `text` (string): Printed below the name; missing when none. ITC: `VM: <name>` of the virtual machine.
  - `total` (number): Net total of the position.
  - `unitPrice` (number): Missing when no price is known (a problem).
  - `usageItemIds` (array of string (uuid)): The usage items of a `usage` line.
- `month` (integer): Month (1–12) of the billing month.
- `netTotal` (number): Net total of the invoice.
- `postedAt` (string (date-time)): When the invoice was posted.
- `problems` (array of string): Each blocks the approval (e.g. "Preisänderung für Artikel … wartet auf Freigabe (… → … €)." while a price suggestion of a billed article is open).
- `stale` (boolean): Usage, a mapping or a contract position changed after the computation: recompute before approving.
- `status` (string): Status of the MSP invoice (`draft`, `approved`, `posting`, `posted`, `failed`). (one of `draft`, `approved`, `posting`, `posted`, `failed`)
- `transactionId` (string (uuid)): The booked INVOICE in trade.
- `transactionNumber` (string): Number of the invoice in Verkauf once posted.
- `year` (integer): Year of the billing month.

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "attempts": 0,
  "computedAt": "2026-11-03T06:12:00Z",
  "delivery": "send",
  "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
  "lines": [
    {
      "articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
      "kind": "usage",
      "name": "Microsoft 365 Business Standard 1YM",
      "position": 1,
      "provider": "ingram",
      "quantity": 12,
      "sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
      "total": 150,
      "unitPrice": 12.5,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01"
      ]
    },
    {
      "articleNumber": "ITC7030222P1MM",
      "kind": "usage",
      "name": "ITC CLOUD Server CPU Performance Plus",
      "position": 2,
      "provider": "itc",
      "quantity": 4,
      "sourceSku": "7030222",
      "text": "VM: kanzlei-srv01",
      "total": 38,
      "unitPrice": 9.5,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c11"
      ]
    },
    {
      "articleNumber": "ITC7030220P1MM",
      "kind": "usage",
      "name": "ITC CLOUD Server RAM 1 GB",
      "position": 3,
      "provider": "itc",
      "quantity": 16,
      "sourceSku": "7030220",
      "text": "VM: kanzlei-srv01",
      "total": 51.2,
      "unitPrice": 3.2,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c12"
      ]
    },
    {
      "articleNumber": "ITC7030003P1MM",
      "kind": "usage",
      "name": "ITC CLOUD 3 Wege Storage Standard je GB",
      "position": 4,
      "provider": "itc",
      "quantity": 500,
      "sourceSku": "7030003",
      "text": "VM: kanzlei-srv01",
      "total": 60,
      "unitPrice": 0.12,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c13"
      ]
    },
    {
      "articleNumber": "DL-9005",
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "contractItemId": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
      "kind": "fixed",
      "name": "Supportpauschale Fernwartung, monatlich",
      "position": 5,
      "quantity": 1,
      "total": 180,
      "unitPrice": 180
    }
  ],
  "month": 10,
  "netTotal": 479.2,
  "problems": [],
  "stale": false,
  "status": "draft",
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get an MSP invoice as the customer will read it (tenant:trade:msp:read)

`GET /api/trade/v1/msp/invoices/{id}/sheet`

Module: Trade · operationId: `getMspInvoiceSheet` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

The Verkauf document once the MSP invoice has one (`transactionId`), else the preview of what approving books:
address, payment terms, company profile with bank account, lines, VAT and totals. Same answer as
`getInvoiceSheet`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** The sheet (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `document` (Transaction, required)
  - `addressId` (string (uuid)): Masterdata address of the partner.
  - `createdAt` (string (date-time), read-only): When the transaction was created.
  - `currency` (string): ISO 4217; EUR when empty.
  - `customerNo` (string, read-only): Customer number of the tenant.
  - `deliveryDate` (string (date-time)): Delivery date.
  - `documentDate` (string (date-time)): Today when empty on create.
  - `documentRefId` (string (uuid)): DMS document of the transaction.
  - `dueDate` (string (date-time)): Due date.
  - `eInvoiceValidation` (object, read-only): The newest e-invoice check of the document (details: `getInvoiceValidation`). Set only for invoices and credit notes, only on reads (`listTransactions`, `getTransaction`), and absent when no check ran.
  - `error` (string, read-only): Error of the last processing (e.g. of an inbound invoice).
  - `exchangeRate` (number): 1 when empty.
  - `externalTransactionNumber` (string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).
  - `footerText` (string): Text printed below the lines.
  - `frozenSnapshot` (object, read-only): Evidence copy of an accepted offer; written once.
  - `grossTotal` (number, read-only): Gross total, computed from the lines.
  - `headerText` (string): Text printed above the lines.
  - `id` (string (uuid), read-only): Id of the transaction.
  - `items` (array of TransactionLine): Lines; on update they replace all lines when present.
    - `name` (string, required): Name of the article or line.
    - `quantity` (number, required): Quantity.
    - `articleNumber` (string): Article number in masterdata.
    - `createdAt` (string (date-time), read-only): When the line was created.
    - `description` (string): Description of the line.
    - `discountPercent` (number): Discount in percent.
    - `ean` (string): EAN (GTIN) of the article.
    - `id` (string (uuid), read-only): Id of the line.
    - `isOptional` (boolean): The line is optional (position type `optional`).
    - `isSelected` (boolean): Selected optional lines count in the totals.
    - `lineData` (object): Facts of the line by type (e.g. serial numbers, sources).
    - `mpn` (string): Manufacturer part number.
    - `parentItemId` (string (uuid)): Line this line belongs to (e.g. a component of a bundle).
    - `positionNumber` (integer, read-only): Set from the order of `items`.
    - `positionType` (PositionType)
    - `predecessorLineId` (string (uuid), read-only): The line of the previous version.
    - `productId` (string (uuid)): Masterdata article (product) id.
    - `sortOrder` (integer): Sort order (ascending).
    - `sourceLineId` (string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.
    - `taxRate` (number): Percent.
    - `totalPriceGross` (number, read-only): Gross total of the line, computed.
    - `totalPriceNet` (number, read-only): Net total of the line, computed.
    - `transactionId` (string (uuid), read-only): Id of the transaction.
    - `unit` (string): Unit of measure.
    - `unitPriceNet` (number): Negative for a credit position.
    - `updatedAt` (string (date-time), read-only): When the line was last changed.
  - `metadata` (object): `metadata.workflow` is owned by the workflow module and kept on every write.
  - `netDays` (integer): Days until the net amount is due.
  - `netTotal` (number, read-only): Computed from the lines.
  - `numberPending` (boolean, read-only): A draft invoice or credit note another module made: `transactionNumber` is its id until `releaseTransaction` gives it the gapless number. Edits keep its number and status.
  - `opportunityId` (string (uuid)): The crm opportunity the document was made for. Only the format is checked (400 `invalid`, `field` `opportunityId`). A document made from another one (`sourceTransactionId`, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the events `trade.transaction.*` and `trade.offer.accepted`.
  - `partnerReference` (string): The partner's order reference (BT-13).
  - `paymentMethodCode` (string): Code of the payment method in masterdata.
  - `paymentTermCode` (string): Code of the payment terms: a snapshot taken when the document is made.
  - `paymentTermsText` (string): Payment terms as printed text.
  - `predecessorId` (string (uuid)): Previous version of the same document.
  - `recipientAddress` (object): Address snapshot of the partner.
  - `recipientCompany` (string): Company of the recipient.
  - `recipientEmail` (string): E-mail of the recipient.
  - `recipientName` (string): Name of the recipient.
  - `skontoDays1` (integer): Days of the first cash discount.
  - `skontoDays2` (integer): Days of the second cash discount.
  - `skontoRate1` (number): Rate in percent of the first cash discount.
  - `skontoRate2` (number): Rate in percent of the second cash discount.
  - `sourceKind` (string): Where it came from: `MANUAL` (default), `PORTAL`, or the e-invoice/OCR kind of inbound invoices.
  - `sourceTransactionId` (string (uuid)): Document this one was made from.
  - `status` (TransactionStatus): Sales statuses are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g. `open`, `posted`, `MATCHED`, `issued`).
  - `taxTotal` (number, read-only): Tax total, computed from the lines.
  - `tenantName` (string, read-only): Name of the tenant.
  - `transactionNumber` (string): Assigned with the type's prefix when empty on create.
  - `transactionType` (string): Code of a type of the tenant's catalogue; required on create.
  - `typeData` (object): Facts of exactly one type (e.g. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
  - `updatedAt` (string (date-time), read-only): When the transaction was last changed.
  - `validUntil` (string (date-time)): Offers only.
  - `version` (integer, read-only): Version of the document (`createTransactionRevision` adds one).
- `problems` (array of string, required): What is missing to read the sheet completely, in German.
- `taxes` (array of object, required): VAT per rate of the billable lines, ordered by rate.
  - `net` (number, required): Net amount taxed at the rate.
  - `rate` (number, required): Tax rate in percent.
  - `tax` (number, required): Tax amount at the rate.
- `buyer` (object): Invoice address of the customer (absent without a masterdata address).
  - `name` (string, required): Name of the buyer.
  - `addressLine2` (string): Second address line.
  - `buyerReference` (string): Buyer reference (Leitweg-ID, BT-10).
  - `city` (string): City.
  - `countryCode` (string): Country code (ISO 3166-1 alpha-2).
  - `customerNumber` (string): Customer number of the buyer.
  - `email` (string): E-mail address.
  - `postalCode` (string): Postal code.
  - `street` (string): Street and house number.
  - `vatId` (string): VAT identification number.
- `seller` (object): The tenant's company profile (absent without one).
  - `bankName` (string): Name of the bank.
  - `bic` (string): BIC.
  - `city` (string): City.
  - `commercialRegister` (string): Commercial register number.
  - `companyName` (string): Company name of the seller.
  - `companyNameAddition` (string): Addition to the company name.
  - `contactEmail` (string): E-mail of the contact person.
  - `contactName` (string): Name of the contact person.
  - `contactPhone` (string): Phone of the contact person.
  - `countryCode` (string): Country code (ISO 3166-1 alpha-2).
  - `electronicAddress` (string): Electronic address of the seller (BT-34).
  - `email` (string): E-mail address.
  - `iban` (string): IBAN.
  - `managingDirectors` (string): Managing directors.
  - `phone` (string): Phone number.
  - `postalCode` (string): Postal code.
  - `registerCourt` (string): Register court.
  - `sepaCreditorId` (string): SEPA creditor id.
  - `street` (string): Street and house number.
  - `taxNumber` (string): Tax number.
  - `vatId` (string): VAT identification number.
  - `website` (string): Website.

Example 200 answer:

```json
{
  "buyer": {
    "city": "Regensburg",
    "countryCode": "DE",
    "customerNumber": "10002",
    "email": "f.pichler@hofmann-partner.example",
    "name": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
    "postalCode": "93047",
    "street": "Maximilianstraße 21"
  },
  "document": {
    "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
    "currency": "EUR",
    "documentDate": "2026-11-05T00:00:00Z",
    "grossTotal": 570.25,
    "headerText": "MSP-Abrechnung Oktober 2026",
    "items": [
      {
        "articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
        "name": "Microsoft 365 Business Standard 1YM",
        "positionNumber": 1,
        "quantity": 12,
        "taxRate": 19,
        "totalPriceNet": 150,
        "unit": "LIZ",
        "unitPriceNet": 12.5
      },
      {
        "articleNumber": "ITC7030222P1MM",
        "description": "VM: kanzlei-srv01",
        "name": "ITC CLOUD Server CPU Performance Plus",
        "positionNumber": 2,
        "quantity": 4,
        "taxRate": 19,
        "totalPriceNet": 38,
        "unit": "MON",
        "unitPriceNet": 9.5
      },
      {
        "articleNumber": "ITC7030220P1MM",
        "description": "VM: kanzlei-srv01",
        "name": "ITC CLOUD Server RAM 1 GB",
        "positionNumber": 3,
        "quantity": 16,
        "taxRate": 19,
        "totalPriceNet": 51.2,
        "unit": "MON",
        "unitPriceNet": 3.2
      },
      {
        "articleNumber": "ITC7030003P1MM",
        "description": "VM: kanzlei-srv01",
        "name": "ITC CLOUD 3 Wege Storage Standard je GB",
        "positionNumber": 4,
        "quantity": 500,
        "taxRate": 19,
        "totalPriceNet": 60,
        "unit": "MON",
        "unitPriceNet": 0.12
      },
      {
        "articleNumber": "DL-9005",
        "name": "Supportpauschale Fernwartung, monatlich",
        "positionNumber": 5,
        "quantity": 1,
        "taxRate": 19,
        "totalPriceNet": 180,
        "unit": "MON",
        "unitPriceNet": 180
      }
    ],
    "netDays": 30,
    "netTotal": 479.2,
    "paymentTermsText": "30 Tage netto",
    "recipientCompany": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
    "status": "DRAFT",
    "taxTotal": 91.05,
    "transactionType": "INVOICE"
  },
  "problems": [],
  "seller": {
    "bankName": "Deutsche Kreditbank",
    "bic": "BYLADEM1001",
    "city": "Regensburg",
    "companyName": "Muster IT-Systemhaus GmbH",
    "countryCode": "DE",
    "email": "info@muster-it.example",
    "iban": "DE02120300000000202051",
    "postalCode": "93055",
    "street": "Industriestraße 12",
    "vatId": "DE999000111"
  },
  "taxes": [
    {
      "net": 479.2,
      "rate": 19,
      "tax": 91.05
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/sheet' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Approve an MSP invoice for booking (tenant:trade:msp:approve)

`POST /api/trade/v1/msp/invoices/{id}/approve`

Module: Trade · operationId: `approveMspInvoice` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Only a fresh draft without problems (or a failed invoice) can be approved. Trade then books it as an `INVOICE`
(Verkauf) with the idempotency key of customer and month, so a customer's month is booked exactly once, also
after a restart or a lost answer; the document number is written back and `trade.msp.invoice.created` is
published. A failed attempt is retried a minute later, three times per approval.

Approval means the poster issues the invoice in Verkauf: final document number, XRechnung with the KoSIT
check, the XML filed in DMS, and the mail with the XML to the customer when the delivery is `send`. A refusal (e.g. the
KoSIT check) leaves the MSP invoice `failed` with `error` and the `transactionId` of the Verkauf draft.
The Verkauf draft carries `typeData.issueRefusal`; issuing it in Verkauf (`issueInvoiceDraft`) marks the refused MSP
invoice `posted`.
Approval needs every active connector to have collected the month (`409` `collection_incomplete`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `delivery` (object): Replaces the invoice's delivery before approving; empty keeps it.

Example:

```json
{
  "delivery": "send"
}
```

### Responses

- **200** Approved (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The state does not allow it: `month_closed` (an invoice of the month is approved or booked), `msp_disabled`, `collection_incomplete` (not every active connector has collected the month), `run_in_progress`, `itc_not_enabled` and `itc_no_supplier` (upload only), or `conflict` (e.g. a stale draft, open problems, an invoice past draft). (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid)): Masterdata address of the customer.
- `addressName` (string): Name of the customer.
- `approvedAt` (string (date-time)): When the invoice was approved.
- `approvedBy` (string): Who approved the invoice.
- `attempts` (integer): Number of posting attempts.
- `computedAt` (string (date-time)): When the draft was computed.
- `delivery` (MspDelivery): `send`: approving issues the invoice in Verkauf and mails it to the customer; `issue`: it is only issued (final number, XRechnung, the XML in DMS). (one of `send`, `issue`)
- `error` (string): Why the last posting failed.
- `id` (string (uuid)): Id of the MSP invoice.
- `lines` (array of MspInvoiceLine): Positions of the invoice.
  - `articleNumber` (string): Article number in masterdata.
  - `contractId` (string (uuid)): Contract of the position.
  - `contractItemId` (string (uuid)): The contract position of a `fixed` line.
  - `kind` (string): `fixed` (a contract item) or `usage` (collected usage). (one of `fixed`, `usage`)
  - `name` (string): Name printed on the invoice position.
  - `position` (integer): Position number of the line.
  - `problem` (string): Why the position cannot be billed as it is.
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `quantity` (number): Quantity.
  - `sourceSku` (string): The provider's SKU.
  - `text` (string): Printed below the name; missing when none. ITC: `VM: <name>` of the virtual machine.
  - `total` (number): Net total of the position.
  - `unitPrice` (number): Missing when no price is known (a problem).
  - `usageItemIds` (array of string (uuid)): The usage items of a `usage` line.
- `month` (integer): Month (1–12) of the billing month.
- `netTotal` (number): Net total of the invoice.
- `postedAt` (string (date-time)): When the invoice was posted.
- `problems` (array of string): Each blocks the approval (e.g. "Preisänderung für Artikel … wartet auf Freigabe (… → … €)." while a price suggestion of a billed article is open).
- `stale` (boolean): Usage, a mapping or a contract position changed after the computation: recompute before approving.
- `status` (string): Status of the MSP invoice (`draft`, `approved`, `posting`, `posted`, `failed`). (one of `draft`, `approved`, `posting`, `posted`, `failed`)
- `transactionId` (string (uuid)): The booked INVOICE in trade.
- `transactionNumber` (string): Number of the invoice in Verkauf once posted.
- `year` (integer): Year of the billing month.

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "approvedAt": "2026-11-05T09:12:00Z",
  "approvedBy": "laura.kaestner@muster-it.example",
  "attempts": 0,
  "computedAt": "2026-11-03T06:12:00Z",
  "delivery": "send",
  "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
  "lines": [
    {
      "articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
      "kind": "usage",
      "name": "Microsoft 365 Business Standard 1YM",
      "position": 1,
      "provider": "ingram",
      "quantity": 12,
      "sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
      "total": 150,
      "unitPrice": 12.5,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01"
      ]
    },
    {
      "articleNumber": "ITC7030222P1MM",
      "kind": "usage",
      "name": "ITC CLOUD Server CPU Performance Plus",
      "position": 2,
      "provider": "itc",
      "quantity": 4,
      "sourceSku": "7030222",
      "text": "VM: kanzlei-srv01",
      "total": 38,
      "unitPrice": 9.5,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c11"
      ]
    },
    {
      "articleNumber": "ITC7030220P1MM",
      "kind": "usage",
      "name": "ITC CLOUD Server RAM 1 GB",
      "position": 3,
      "provider": "itc",
      "quantity": 16,
      "sourceSku": "7030220",
      "text": "VM: kanzlei-srv01",
      "total": 51.2,
      "unitPrice": 3.2,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c12"
      ]
    },
    {
      "articleNumber": "ITC7030003P1MM",
      "kind": "usage",
      "name": "ITC CLOUD 3 Wege Storage Standard je GB",
      "position": 4,
      "provider": "itc",
      "quantity": 500,
      "sourceSku": "7030003",
      "text": "VM: kanzlei-srv01",
      "total": 60,
      "unitPrice": 0.12,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c13"
      ]
    },
    {
      "articleNumber": "DL-9005",
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "contractItemId": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
      "kind": "fixed",
      "name": "Supportpauschale Fernwartung, monatlich",
      "position": 5,
      "quantity": 1,
      "total": 180,
      "unitPrice": 180
    }
  ],
  "month": 10,
  "netTotal": 479.2,
  "problems": [],
  "stale": false,
  "status": "approved",
  "year": 2026
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/approve' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"delivery":"send"}'
```

## Turn a failed MSP invoice back into a draft (tenant:trade:msp:approve)

`POST /api/trade/v1/msp/invoices/{id}/reopen`

Module: Trade · operationId: `reopenMspInvoice` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

The draft is stale and must be recomputed before it can be approved again.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Draft (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)
- **409** The state does not allow it: `month_closed` (an invoice of the month is approved or booked), `msp_disabled`, `collection_incomplete` (not every active connector has collected the month), `run_in_progress`, `itc_not_enabled` and `itc_no_supplier` (upload only), or `conflict` (e.g. a stale draft, open problems, an invoice past draft). (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid)): Masterdata address of the customer.
- `addressName` (string): Name of the customer.
- `approvedAt` (string (date-time)): When the invoice was approved.
- `approvedBy` (string): Who approved the invoice.
- `attempts` (integer): Number of posting attempts.
- `computedAt` (string (date-time)): When the draft was computed.
- `delivery` (MspDelivery): `send`: approving issues the invoice in Verkauf and mails it to the customer; `issue`: it is only issued (final number, XRechnung, the XML in DMS). (one of `send`, `issue`)
- `error` (string): Why the last posting failed.
- `id` (string (uuid)): Id of the MSP invoice.
- `lines` (array of MspInvoiceLine): Positions of the invoice.
  - `articleNumber` (string): Article number in masterdata.
  - `contractId` (string (uuid)): Contract of the position.
  - `contractItemId` (string (uuid)): The contract position of a `fixed` line.
  - `kind` (string): `fixed` (a contract item) or `usage` (collected usage). (one of `fixed`, `usage`)
  - `name` (string): Name printed on the invoice position.
  - `position` (integer): Position number of the line.
  - `problem` (string): Why the position cannot be billed as it is.
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `quantity` (number): Quantity.
  - `sourceSku` (string): The provider's SKU.
  - `text` (string): Printed below the name; missing when none. ITC: `VM: <name>` of the virtual machine.
  - `total` (number): Net total of the position.
  - `unitPrice` (number): Missing when no price is known (a problem).
  - `usageItemIds` (array of string (uuid)): The usage items of a `usage` line.
- `month` (integer): Month (1–12) of the billing month.
- `netTotal` (number): Net total of the invoice.
- `postedAt` (string (date-time)): When the invoice was posted.
- `problems` (array of string): Each blocks the approval (e.g. "Preisänderung für Artikel … wartet auf Freigabe (… → … €)." while a price suggestion of a billed article is open).
- `stale` (boolean): Usage, a mapping or a contract position changed after the computation: recompute before approving.
- `status` (string): Status of the MSP invoice (`draft`, `approved`, `posting`, `posted`, `failed`). (one of `draft`, `approved`, `posting`, `posted`, `failed`)
- `transactionId` (string (uuid)): The booked INVOICE in trade.
- `transactionNumber` (string): Number of the invoice in Verkauf once posted.
- `year` (integer): Year of the billing month.

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "attempts": 0,
  "computedAt": "2026-11-03T06:12:00Z",
  "delivery": "send",
  "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
  "lines": [
    {
      "articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
      "kind": "usage",
      "name": "Microsoft 365 Business Standard 1YM",
      "position": 1,
      "provider": "ingram",
      "quantity": 12,
      "sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
      "total": 150,
      "unitPrice": 12.5,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01"
      ]
    },
    {
      "articleNumber": "ITC7030222P1MM",
      "kind": "usage",
      "name": "ITC CLOUD Server CPU Performance Plus",
      "position": 2,
      "provider": "itc",
      "quantity": 4,
      "sourceSku": "7030222",
      "text": "VM: kanzlei-srv01",
      "total": 38,
      "unitPrice": 9.5,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c11"
      ]
    },
    {
      "articleNumber": "ITC7030220P1MM",
      "kind": "usage",
      "name": "ITC CLOUD Server RAM 1 GB",
      "position": 3,
      "provider": "itc",
      "quantity": 16,
      "sourceSku": "7030220",
      "text": "VM: kanzlei-srv01",
      "total": 51.2,
      "unitPrice": 3.2,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c12"
      ]
    },
    {
      "articleNumber": "ITC7030003P1MM",
      "kind": "usage",
      "name": "ITC CLOUD 3 Wege Storage Standard je GB",
      "position": 4,
      "provider": "itc",
      "quantity": 500,
      "sourceSku": "7030003",
      "text": "VM: kanzlei-srv01",
      "total": 60,
      "unitPrice": 0.12,
      "usageItemIds": [
        "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c13"
      ]
    },
    {
      "articleNumber": "DL-9005",
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "contractItemId": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
      "kind": "fixed",
      "name": "Supportpauschale Fernwartung, monatlich",
      "position": 5,
      "quantity": 1,
      "total": 180,
      "unitPrice": 180
    }
  ],
  "month": 10,
  "netTotal": 479.2,
  "problems": [],
  "stale": false,
  "status": "draft",
  "year": 2026
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/reopen' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the customer mappings (tenant:trade:msp:read)

`GET /api/trade/v1/msp/mappings/customers`

Module: Trade · operationId: `listMspCustomerMappings` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Mappings (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `items` (array of MspCustomerMapping)
  - `addressId` (string (uuid), required): Masterdata address that is billed.
  - `provider` (string, required): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …). (max length 32)
  - `sourceCustomer` (string, required): The provider's customer (id or name). (max length 200)
  - `addressName` (string): Name of the masterdata address. (max length 300)
  - `adrNr` (string): Adressnummer of the masterdata address. Optional in a PUT (taken from the address the person picked); without it a save to the same address keeps the stored number, a save to another address clears it. AutoMap fills it from masterdata's match. (max length 64)
  - `contractId` (string (uuid)): Contract the usage belongs to (its usage positions set prices).
  - `customerNumber` (string): Kundennummer of the masterdata address, the number providers send (Sophos `assignedAccountIdentifier` "11141 | Name", MailStore instance id "k11141"). Optional in a PUT, same rules as `adrNr`. (max length 64)
  - `id` (string (uuid), read-only): Id of the mapping.
  - `matchedBy` (string, read-only): Rule of an automatic mapping or a suggestion (`adrNr`: an Ingram end customer whose Custom_Account_ID is our address number). `created`: only on mappings of earlier versions, which created the masterdata address of an Ingram end customer by themselves. (one of `adrNr`, `customerNumber+address`, `customerNumber`, `name+address`, `name`, `address`, `created`)
  - `source` (string, read-only): `auto`: masterdata has the provider's customer number as an address's customer number, billed like a manual mapping. `suggested`: found by name or postal address only, assigns nothing and bills nothing until it is saved. Every save through the API is manual, also the save of an automatic mapping or a suggestion. (one of `manual`, `auto`, `suggested`)
  - `updatedAt` (string (date-time), read-only): When the mapping was last saved.

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
      "addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "adrNr": "20001",
      "customerNumber": "10001",
      "id": "3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d01",
      "matchedBy": "customerNumber",
      "provider": "sophos",
      "source": "auto",
      "sourceCustomer": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
      "updatedAt": "2026-11-01T05:06:10Z"
    },
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
      "addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "adrNr": "20002",
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "customerNumber": "10002",
      "id": "3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d02",
      "provider": "ingram",
      "source": "manual",
      "sourceCustomer": "1100430325",
      "updatedAt": "2026-02-03T11:00:00Z"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/mappings/customers' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Map a provider's customer to a customer address (tenant:trade:msp:write)

`PUT /api/trade/v1/msp/mappings/customers`

Module: Trade · operationId: `saveMspCustomerMapping` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Creates or replaces the mapping of provider and provider customer. Drafts become stale.

### Request body

`application/json` (required)

- `addressId` (string (uuid), required): Masterdata address that is billed.
- `provider` (string, required): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …). (max length 32)
- `sourceCustomer` (string, required): The provider's customer (id or name). (max length 200)
- `addressName` (string): Name of the masterdata address. (max length 300)
- `adrNr` (string): Adressnummer of the masterdata address. Optional in a PUT (taken from the address the person picked); without it a save to the same address keeps the stored number, a save to another address clears it. AutoMap fills it from masterdata's match. (max length 64)
- `contractId` (string (uuid)): Contract the usage belongs to (its usage positions set prices).
- `customerNumber` (string): Kundennummer of the masterdata address, the number providers send (Sophos `assignedAccountIdentifier` "11141 | Name", MailStore instance id "k11141"). Optional in a PUT, same rules as `adrNr`. (max length 64)
- `id` (string (uuid), read-only): Id of the mapping.
- `matchedBy` (string, read-only): Rule of an automatic mapping or a suggestion (`adrNr`: an Ingram end customer whose Custom_Account_ID is our address number). `created`: only on mappings of earlier versions, which created the masterdata address of an Ingram end customer by themselves. (one of `adrNr`, `customerNumber+address`, `customerNumber`, `name+address`, `name`, `address`, `created`)
- `source` (string, read-only): `auto`: masterdata has the provider's customer number as an address's customer number, billed like a manual mapping. `suggested`: found by name or postal address only, assigns nothing and bills nothing until it is saved. Every save through the API is manual, also the save of an automatic mapping or a suggestion. (one of `manual`, `auto`, `suggested`)
- `updatedAt` (string (date-time), read-only): When the mapping was last saved.

Example:

```json
{
  "addressId": "3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10",
  "addressName": "Muster GmbH",
  "provider": "sophos",
  "sourceCustomer": "5b1d6a0e-2f4c-4d1b-9a3e-7c8f0e1d2a3b"
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid), required): Masterdata address that is billed.
- `provider` (string, required): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …). (max length 32)
- `sourceCustomer` (string, required): The provider's customer (id or name). (max length 200)
- `addressName` (string): Name of the masterdata address. (max length 300)
- `adrNr` (string): Adressnummer of the masterdata address. Optional in a PUT (taken from the address the person picked); without it a save to the same address keeps the stored number, a save to another address clears it. AutoMap fills it from masterdata's match. (max length 64)
- `contractId` (string (uuid)): Contract the usage belongs to (its usage positions set prices).
- `customerNumber` (string): Kundennummer of the masterdata address, the number providers send (Sophos `assignedAccountIdentifier` "11141 | Name", MailStore instance id "k11141"). Optional in a PUT, same rules as `adrNr`. (max length 64)
- `id` (string (uuid), read-only): Id of the mapping.
- `matchedBy` (string, read-only): Rule of an automatic mapping or a suggestion (`adrNr`: an Ingram end customer whose Custom_Account_ID is our address number). `created`: only on mappings of earlier versions, which created the masterdata address of an Ingram end customer by themselves. (one of `adrNr`, `customerNumber+address`, `customerNumber`, `name+address`, `name`, `address`, `created`)
- `source` (string, read-only): `auto`: masterdata has the provider's customer number as an address's customer number, billed like a manual mapping. `suggested`: found by name or postal address only, assigns nothing and bills nothing until it is saved. Every save through the API is manual, also the save of an automatic mapping or a suggestion. (one of `manual`, `auto`, `suggested`)
- `updatedAt` (string (date-time), read-only): When the mapping was last saved.

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c03",
  "addressName": "Bäckerei Sonnleitner GmbH",
  "adrNr": "20003",
  "customerNumber": "10003",
  "id": "3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d03",
  "provider": "sophos",
  "source": "manual",
  "sourceCustomer": "6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0",
  "updatedAt": "2026-11-19T10:40:00Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/msp/mappings/customers' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10","addressName":"Muster GmbH","provider":"sophos","sourceCustomer":"5b1d6a0e-2f4c-4d1b-9a3e-7c8f0e1d2a3b"}'
```

## Delete a customer mapping (tenant:trade:msp:write)

`DELETE /api/trade/v1/msp/mappings/customers/{id}`

Module: Trade · operationId: `deleteMspCustomerMapping` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/trade/v1/msp/mappings/customers/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Look up the month's unmapped usage in masterdata (tenant:trade:msp:write)

`POST /api/trade/v1/msp/mappings/auto`

Module: Trade · operationId: `autoMapMspUsage` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Looks up the month's usage items without customer or article in masterdata. Every succeeded run does the same
after it completes; a masterdata failure never fails the run. A mapping a person saved is never changed.

Customer: masterdata's match is found by customer number (`customerHint`), else by exact name; each is
confirmed by an equal postal address when the provider sent one (Sophos: contact address). Else the postal
address alone. If masterdata has the provider's customer number as an address's customer number (rules
`customerNumber`, `customerNumber+address`) the mapping is **automatic** (`source: auto`) and billed like a
manual one; a match by name or postal address only is **suggested** (`source: suggested`) and bills nothing.
Saving a suggestion with `PUT /api/trade/v1/msp/mappings/customers` makes it manual, and the next billing
computation uses it. An earlier automatic mapping or suggestion is updated when masterdata now names another
customer. The address's `adrNr` and `customerNumber` are stored with the mapping.

Ingram end customers are read from the Cloud Marketplace API when its access is configured (`msp.ingram.marketplace*`
of the config): its `attributes.Custom_Account_ID` is our address number, matched first (`matchedBy: adrNr`). Every customer looked up is recorded as a
provider customer; one that is not mapped automatically is listed by `GET /api/trade/v1/msp/customers/open`.
MSP billing never creates a masterdata address.

Article: the one article whose manufacturer part number equals the SKU is mapped (`source: auto`); with two
such articles nothing is mapped. A Microsoft SKU of Ingram is an article per term: its usage SKU carries the
term (`CFQ7TTC0MBMD:0002/P1YM` – P1YM a year billed monthly, P1YA a year billed yearly, P1MM a month billed
monthly, P10YT ten years billed once; a mapping of the bare SKU still applies to every term). It is mapped to the article numbered `MSFT` + the
SKU without `:` + the term (`MSFTCFQ7TTC0MBMD0002P1YM`, `matchedBy: articleNumber`); when masterdata has none and
`msp.ingram.articleUnitCode` and `articleProductGroupId` are set, that article is created (`matchedBy: created`:
Suchbegriff and manufacturer part number the SKU, Kurzbezeichnung the subscription's name with the term
(`Microsoft 365 F1 1YM`), article type `SUBSCRIPTION` billed in advance with the term's months, no serial numbers,
sales price Ingram's `unitPrice`, the Ingram supplier with Ingram's `unitCost` as purchase price and the article
number without `MSFT`). A Sophos SKU no article carries as part number gets the article `SOPH` + the SKU without
`-` + `P1MM` (`SOPHCIXA0UDAC3P1MM`), found by that number or created from the Infinigate catalog with
`msp.sophos.articleUnitCode` and `articleProductGroupId` set (Infinigate's description, list price as sales price,
the supplier with Infinigate's discounted price, Abonnement of one month); a SKU Infinigate does not know gets
none. Every succeeded run does this by itself; this route repeats it for the month. Drafts become
stale when article mappings were added.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |

### Responses

- **200** How many customer mappings (automatic or suggested) were added or changed and how many article mappings were added. (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `articles` (integer): Article mappings added.
- `createdArticles` (integer): Microsoft and Sophos articles created in masterdata (mapped too).
- `customers` (integer): Customer suggestions added or changed.
- `replacedArticles` (integer): Part-number fallbacks of Microsoft SKUs and terms (rule manufacturerPartNumberBare) that now point at their own article.

Example 200 answer:

```json
{
  "articles": 5,
  "createdArticles": 2,
  "customers": 3,
  "replacedArticles": 0
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/mappings/auto' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Read the latest customer sync (tenant:trade:msp:read)

`GET /api/trade/v1/msp/customers/sync`

Module: Trade · operationId: `getMspCustomerSync` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

The state of the tenant's latest „Jetzt zuordnen“; `status` is `none` before the first one.

### Responses

- **200** The latest sync. (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `error` (string): Why the sync failed.
- `finishedAt` (string (date-time)): When it finished; absent while running.
- `result` (object): Outcome per provider.
  - `mapped` (integer): Customers mapped automatically by their customer number.
  - `open` (integer): Provider customers to clarify after the sync.
  - `providers` (array of object): Outcome per provider.
    - `customers` (integer): Customers the provider listed.
    - `error` (string): Why the provider could not be read.
    - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
- `startedAt` (string (date-time)): When it started.
- `status` (string): Status of the sync (`running`, `succeeded`, `failed`). (one of `none`, `running`, `succeeded`, `failed`)
- `triggeredBy` (string): Who started the sync.

Example 200 answer:

```json
{
  "finishedAt": "2026-11-18T13:01:42Z",
  "result": {
    "mapped": 3,
    "open": 5,
    "providers": [
      {
        "customers": 9,
        "provider": "mailstore"
      },
      {
        "customers": 18,
        "provider": "sophos"
      },
      {
        "customers": 24,
        "provider": "ingram"
      }
    ]
  },
  "startedAt": "2026-11-18T13:00:00Z",
  "status": "succeeded",
  "triggeredBy": "anna.weber@muster-it.example"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/customers/sync' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Fetch the providers' customers and map them (tenant:trade:msp:write)

`POST /api/trade/v1/msp/customers/sync`

Module: Trade · operationId: `startMspCustomerSync` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

„Jetzt zuordnen“: asks every enabled provider for its end customers – MailStore its instances, Sophos the
accounts of the usage of this and the previous month, Ingram the end customers of its subscriptions (read from
the Cloud Marketplace API when configured) – and records them as provider customers. A customer with a manual
or automatic mapping is left alone. An unmapped one whose customer number masterdata has as an address's
customer number is mapped automatically (`source: auto`); one masterdata finds by name or postal address only
gets a suggestion; every other one stays open (`GET /api/trade/v1/msp/customers/open`) until a person maps it to an
existing address. Nothing is created in masterdata.

The sync runs in the background: the answer is `202` with the running sync; follow it with
`GET /api/trade/v1/msp/customers/sync`. One sync per tenant at a time (`409 sync_running`).

### Responses

- **202** The sync started. (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **409** A sync of the tenant runs already (`sync_running`) or MSP billing is off (`msp_disabled`). (`application/json`)

Fields of the 202 answer:

- `error` (string): Why the sync failed.
- `finishedAt` (string (date-time)): When it finished; absent while running.
- `result` (object): Outcome per provider.
  - `mapped` (integer): Customers mapped automatically by their customer number.
  - `open` (integer): Provider customers to clarify after the sync.
  - `providers` (array of object): Outcome per provider.
    - `customers` (integer): Customers the provider listed.
    - `error` (string): Why the provider could not be read.
    - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
- `startedAt` (string (date-time)): When it started.
- `status` (string): Status of the sync (`running`, `succeeded`, `failed`). (one of `none`, `running`, `succeeded`, `failed`)
- `triggeredBy` (string): Who started the sync.

Example 202 answer:

```json
{
  "startedAt": "2026-11-18T13:00:00Z",
  "status": "running",
  "triggeredBy": "anna.weber@muster-it.example"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/customers/sync' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the provider customers to clarify (tenant:trade:msp:read)

`GET /api/trade/v1/msp/customers/open`

Module: Trade · operationId: `listOpenMspCustomers` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Provider customers without a customer mapping, or with only a suggestion (`suggestion`), that no contract
assigns by its CSP tenant id. A person takes the suggestion or picks an existing address
(`PUT /api/trade/v1/msp/mappings/customers`, several at once: `POST /api/trade/v1/msp/customers/decide`).

### Responses

- **200** The open provider customers, by provider and name. (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `items` (array of MspOpenProviderCustomer)

Example 200 answer:

```json
{
  "items": [
    {
      "city": "Passau",
      "contact": {
        "email": "josef@baeckerei-sonnleitner.example",
        "firstName": "Josef",
        "lastName": "Sonnleitner"
      },
      "countryCode": "DE",
      "firstSeenAt": "2026-11-02T05:01:00Z",
      "lastSeenAt": "2026-11-18T13:01:30Z",
      "name": "Bäckerei Sonnleitner GmbH",
      "postalCode": "94032",
      "provider": "sophos",
      "sourceCustomer": "6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0",
      "street": "Hauptstraße 55",
      "subscriptions": [
        {
          "product": "Sophos Intercept X Advanced",
          "quantity": 9,
          "sku": "CIXA0UDAC",
          "status": "ACTIVE",
          "unit": "Gerät"
        }
      ],
      "suggestion": {
        "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c03",
        "addressName": "Bäckerei Sonnleitner GmbH",
        "adrNr": "20003",
        "customerNumber": "10003",
        "matchedBy": "name+address",
        "provider": "sophos",
        "source": "suggested",
        "sourceCustomer": "6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0",
        "updatedAt": "2026-11-18T13:01:30Z"
      }
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/customers/open' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Decide several provider customers to clarify at once (tenant:trade:msp:write)

`POST /api/trade/v1/msp/customers/decide`

Module: Trade · operationId: `decideMspCustomers` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Applies one decision to every named provider customer: `accept` takes masterdata's suggestion over, `assign`
maps every customer to the one existing address given (`addressId`, required for it). Each customer is saved
on its own and becomes a manual mapping; the answer names the customers the decision could not apply to with
a `code`: `no_suggestion` or `failed`. No masterdata address is created.

### Request body

`application/json` (required)

- `action` (string, required): (one of `accept`, `assign`)
- `customers` (array of object, required)
  - `provider` (string, required): (max length 32)
  - `sourceCustomer` (string, required): (max length 200)
- `addressId` (string (uuid)): The address of `assign`.
- `addressName` (string): (max length 300)
- `adrNr` (string): (max length 64)
- `customerNumber` (string): (max length 64)

Example:

```json
{
  "action": "accept",
  "customers": [
    {
      "provider": "sophos",
      "sourceCustomer": "6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0"
    },
    {
      "provider": "mailstore",
      "sourceCustomer": "k10004"
    }
  ]
}
```

### Responses

- **200** How many customers were decided, and the refused ones. (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `done` (integer)
- `refused` (array of object)
  - `code` (string): (one of `no_suggestion`, `failed`)
  - `error` (string)
  - `provider` (string)
  - `sourceCustomer` (string)

Example 200 answer:

```json
{
  "done": 1,
  "refused": [
    {
      "code": "no_suggestion",
      "error": "Für diesen Kunden gibt es keinen Vorschlag.",
      "provider": "mailstore",
      "sourceCustomer": "k10004"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/customers/decide' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"accept","customers":[{"provider":"sophos","sourceCustomer":"6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0"},{"provider":"mailstore","sourceCustomer":"k10004"}]}'
```

## List the article mappings (tenant:trade:msp:read)

`GET /api/trade/v1/msp/mappings/articles`

Module: Trade · operationId: `listMspArticleMappings` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Mappings (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `items` (array of MspArticleMapping)
  - `articleNumber` (string, required): Masterdata article that is sold. (max length 100)
  - `provider` (string, required): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …). (max length 32)
  - `sourceSku` (string, required): The provider's SKU. (max length 200)
  - `id` (string (uuid), read-only): Id of the mapping.
  - `matchedBy` (string, read-only): Rule of an automatic mapping: the SKU is the article's manufacturer part number, the bare Microsoft SKU (without term) is the article's manufacturer part number (a fallback replaced by the SKU and term's own article once that exists), the article has the Microsoft or Sophos SKU's number, or the article was created for it. (one of `manufacturerPartNumber`, `manufacturerPartNumberBare`, `articleNumber`, `created`)
  - `name` (string): Line text; empty: the article's name. (max length 300)
  - `source` (string, read-only): Every save through the API is manual, also a save of an automatic mapping. (one of `manual`, `auto`)
  - `unitPrice` (number): Net price; empty: the contract's usage position, else the article's price.
  - `updatedAt` (string (date-time), read-only): When the mapping was last saved.

Example 200 answer:

```json
{
  "items": [
    {
      "articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
      "id": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e01",
      "matchedBy": "articleNumber",
      "name": "Microsoft 365 Business Standard 1YM",
      "provider": "ingram",
      "source": "auto",
      "sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
      "updatedAt": "2026-08-01T05:05:00Z"
    },
    {
      "articleNumber": "CL-3003",
      "id": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e02",
      "name": "E-Mail-Archivierung je Postfach, monatlich",
      "provider": "mailstore",
      "source": "manual",
      "sourceSku": "MB-MAILSTORE",
      "unitPrice": 2.5,
      "updatedAt": "2026-03-02T09:00:00Z"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/mappings/articles' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Map a provider's SKU to an article (tenant:trade:msp:write)

`PUT /api/trade/v1/msp/mappings/articles`

Module: Trade · operationId: `saveMspArticleMapping` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Creates or replaces the mapping of provider and SKU. Drafts become stale.

### Request body

`application/json` (required)

- `articleNumber` (string, required): Masterdata article that is sold. (max length 100)
- `provider` (string, required): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …). (max length 32)
- `sourceSku` (string, required): The provider's SKU. (max length 200)
- `id` (string (uuid), read-only): Id of the mapping.
- `matchedBy` (string, read-only): Rule of an automatic mapping: the SKU is the article's manufacturer part number, the bare Microsoft SKU (without term) is the article's manufacturer part number (a fallback replaced by the SKU and term's own article once that exists), the article has the Microsoft or Sophos SKU's number, or the article was created for it. (one of `manufacturerPartNumber`, `manufacturerPartNumberBare`, `articleNumber`, `created`)
- `name` (string): Line text; empty: the article's name. (max length 300)
- `source` (string, read-only): Every save through the API is manual, also a save of an automatic mapping. (one of `manual`, `auto`)
- `unitPrice` (number): Net price; empty: the contract's usage position, else the article's price.
- `updatedAt` (string (date-time), read-only): When the mapping was last saved.

Example:

```json
{
  "articleNumber": "M365-BP",
  "name": "Microsoft 365 Business Premium",
  "provider": "ingram",
  "sourceSku": "CFQ7TTC0LCHC",
  "unitPrice": 20.6
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)

Fields of the 200 answer:

- `articleNumber` (string, required): Masterdata article that is sold. (max length 100)
- `provider` (string, required): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …). (max length 32)
- `sourceSku` (string, required): The provider's SKU. (max length 200)
- `id` (string (uuid), read-only): Id of the mapping.
- `matchedBy` (string, read-only): Rule of an automatic mapping: the SKU is the article's manufacturer part number, the bare Microsoft SKU (without term) is the article's manufacturer part number (a fallback replaced by the SKU and term's own article once that exists), the article has the Microsoft or Sophos SKU's number, or the article was created for it. (one of `manufacturerPartNumber`, `manufacturerPartNumberBare`, `articleNumber`, `created`)
- `name` (string): Line text; empty: the article's name. (max length 300)
- `source` (string, read-only): Every save through the API is manual, also a save of an automatic mapping. (one of `manual`, `auto`)
- `unitPrice` (number): Net price; empty: the contract's usage position, else the article's price.
- `updatedAt` (string (date-time), read-only): When the mapping was last saved.

Example 200 answer:

```json
{
  "articleNumber": "CL-3003",
  "id": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e02",
  "name": "E-Mail-Archivierung je Postfach, monatlich",
  "provider": "mailstore",
  "source": "manual",
  "sourceSku": "MB-MAILSTORE",
  "unitPrice": 2.5,
  "updatedAt": "2026-11-19T10:45:00Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/msp/mappings/articles' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"articleNumber":"M365-BP","name":"Microsoft 365 Business Premium","provider":"ingram","sourceSku":"CFQ7TTC0LCHC","unitPrice":20.6}'
```

## Delete an article mapping (tenant:trade:msp:write)

`DELETE /api/trade/v1/msp/mappings/articles/{id}`

Module: Trade · operationId: `deleteMspArticleMapping` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **204** Deleted
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/trade/v1/msp/mappings/articles/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Compare purchase and sales of a month per provider (tenant:trade:msp:read)

`GET /api/trade/v1/msp/reconciliation`

Module: Trade · operationId: `getMspReconciliation` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Per provider the inbound invoices of its supplier whose service date (delivery date, else document date) lies
in the month against the MSP invoice lines of the month, per SKU; the supplier is the provider's
`supplierAddressId` in the MSP configuration, else the address masterdata links with the distributor id of the
provider. `backToBack` gives the month's margin of every back-to-back link (MSP sales of the customer contract
against the monthly share of the supplier contract's net amount).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |

### Responses

- **200** Reconciliation (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `backToBack` (array of object): Sales and purchase per back-to-back link.
  - `customerContractId` (string (uuid)): Id of the customer contract.
  - `customerContractNumber` (string): Number of the customer contract.
  - `linkId` (string (uuid)): Id of the back-to-back link.
  - `margin` (number): Sales minus purchase.
  - `purchaseNet` (number): Net purchase.
  - `salesNet` (number): Net sales.
  - `supplierContractId` (string (uuid)): Id of the supplier contract.
  - `supplierContractNumber` (string): Number of the supplier contract.
- `month` (integer): Month (1–12) of the billing month.
- `providers` (array of object): Purchase and sales per provider.
  - `margin` (number): Sales minus purchase.
  - `problem` (string): Why the purchase side is missing.
  - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
  - `purchaseInvoices` (array of object): Inbound invoices of the supplier in the month.
    - `documentDate` (string (date-time)): Invoice date.
    - `id` (string (uuid)): Id of the purchase invoice.
    - `netTotal` (number): Net total.
    - `supplierInvoiceNumber` (string): The supplier's invoice number.
    - `transactionNumber` (string): Number of the inbound invoice.
  - `purchaseNet` (number): Net purchase of the month.
  - `salesBookedNet` (number): Booked MSP invoices only.
  - `salesNet` (number): All MSP invoices of the month, drafts included.
  - `skus` (array of object): Purchase and sales per SKU.
    - `purchasedNet` (number): Net purchase.
    - `purchasedQuantity` (number): Quantity purchased.
    - `sku` (string): The provider's SKU.
    - `soldNet` (number): Net sales.
    - `soldQuantity` (number): Quantity sold.
  - `supplier` (object): Supplier address of the provider.
    - `addressId` (string): Masterdata address of the supplier.
    - `name` (string): Name of the supplier.
- `year` (integer): Year of the billing month.

Example 200 answer:

```json
{
  "backToBack": [
    {
      "customerContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "customerContractNumber": "V-2026-0007",
      "linkId": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d01",
      "margin": 101,
      "purchaseNet": 79,
      "salesNet": 180,
      "supplierContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
      "supplierContractNumber": "LV-2026-0003"
    }
  ],
  "month": 10,
  "providers": [
    {
      "margin": 321.8,
      "provider": "ingram",
      "purchaseInvoices": [
        {
          "documentDate": "2026-11-02T00:00:00Z",
          "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a21",
          "netTotal": 1617.2,
          "supplierInvoiceNumber": "6010009876",
          "transactionNumber": "ER-2026-00041"
        }
      ],
      "purchaseNet": 1617.2,
      "salesBookedNet": 0,
      "salesNet": 1939,
      "skus": [
        {
          "purchasedNet": 499.2,
          "purchasedQuantity": 48,
          "sku": "CFQ7TTC0LDPB:0001/P1YM",
          "soldNet": 600,
          "soldQuantity": 48
        },
        {
          "purchasedNet": 1118,
          "purchasedQuantity": 65,
          "sku": "CFQ7TTC0LCHC:0002/P1YM",
          "soldNet": 1339,
          "soldQuantity": 65
        }
      ],
      "supplier": {
        "addressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10",
        "name": "Ingram Micro Distribution GmbH"
      }
    },
    {
      "margin": 471.6,
      "problem": "Für Oktober 2026 liegt noch keine Eingangsrechnung des Lieferanten vor.",
      "provider": "itc",
      "purchaseInvoices": [],
      "purchaseNet": 0,
      "salesBookedNet": 0,
      "salesNet": 471.6,
      "skus": [],
      "supplier": {
        "addressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03",
        "name": "CloudNine Hosting AG"
      }
    }
  ],
  "year": 2026
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/reconciliation' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Configuration

## Get the trade configuration (tenant:settings:read)

`GET /api/trade/v1/config`

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

The whole module configuration; secrets are masked. A tenant without configuration gets the empty defaults.

### Responses

- **200** Configuration (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `active` (boolean): Trade is active for the tenant.
- `ai` (object): AI settings.
  - `enabledFeatures` (array of string): AI features turned on.
- `inbound` (object): Inbound invoice settings.
  - `autoGoodsReceipt` (AutoGoodsReceiptConfig): Automatic goods receipt for supplier delivery notes whose lines match the open quantities of their purchase order exactly. A note read by AI must also deliver every open line of the order (a partial delivery of the order waits for a person); an EGIS note posts per shipment. Off by default.
    - `minConfidence` (number): Extraction confidence a delivery note needs unless it comes from EGIS (default 0.9).
    - `mode` (string): `off` (default), `dryRun` or `on`. (one of `off`, `dryRun`, `on`)
  - `autoRelease` (AutoReleaseConfig): Automatic release of inbound invoices with a clean 3-way match. Off by default.
    - `excludedSupplierIds` (array of string (uuid)): Supplier addresses that never release themselves; wins over `supplierIds` and history.
    - `maxGrossEur` (number): Highest gross EUR amount that releases itself; required above 0 when the mode is not `off`.
    - `minReleasedInvoices` (integer): Released invoices a supplier needs before it is trusted (default 3).
    - `mode` (string): `off` (default) stores nothing, `dryRun` only stores the verdict (`InboundInvoice.autoRelease`), `on` releases eligible invoices in the transaction that matches them. (one of `off`, `dryRun`, `on`)
    - `supplierIds` (array of string (uuid)): Supplier addresses trusted without history; optional.
  - `fallbackVendorNo` (string): Supplier number used when no supplier is found.
  - `ignoredArticles` (array of string): Article numbers the matching ignores (e.g. freight).
  - `lastRagSync` (string (date-time)): When suppliers and articles were last indexed for matching.
  - `matching` (MatchingTolerances)
    - `allowQuantityOverhang` (boolean): Accept invoiced quantities above the received ones.
    - `maxPriceVarianceAbs` (number): Highest accepted unit price variance as amount (e.g. 2.00 EUR).
    - `maxPriceVariancePercent` (number): Highest accepted unit price variance in percent (1.0 = 1 %).
  - `recipientCity` (string): City of the tenant as invoice recipient.
  - `recipientCountry` (string): Country of the tenant as invoice recipient.
  - `recipientIban` (string): IBAN of the tenant.
  - `recipientName` (string): Our company as invoice recipient (checked on inbound invoices).
  - `recipientStreet` (string): Street of the tenant as invoice recipient.
  - `recipientVatId` (string): VAT id of the tenant as invoice recipient.
  - `recipientZip` (string): Postal code of the tenant as invoice recipient.
  - `strictEInvoice` (boolean): Block invoices without structured XML.
- `itsp` (object): Distributor catalog settings.
  - `aiEnrichment` (AIEnrichmentConfig): Null until saved once.
    - `enabled` (boolean): Propose article texts and product groups with AI.
    - `model` (string): AI model of the enrichment; empty uses the default.
  - `amazon` (AmazonConfig)
    - `baseUrl` (string): Base URL of the API; empty uses the default.
    - `clientId` (string): OAuth client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `enabled` (boolean): Search the Amazon Business catalog.
    - `locale` (string): Locale of the product data (e.g. `de_DE`).
    - `refreshToken` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `region` (string): Amazon region of the account.
    - `sandbox` (boolean): Use the sandbox environment.
    - `userEmail` (string): E-mail of the Amazon Business user the searches run as.
  - `apiKeyId` (string): API key id of the catalog service.
  - `apiKeySecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `baseUrl` (string): Base URL of the catalog service.
  - `customerId` (string): Customer id at the catalog service.
  - `defaultCountryCode` (string): Default country of the catalog searches.
  - `egis` (EgisConfig)
    - `baseUrl` (string): Base URL of the API; empty uses the default.
    - `enabled` (boolean): Search and order through EGIS.
    - `erp` (string): ERP name sent to EGIS; empty uses the default.
    - `login` (string): EGIS login. (max length 40)
    - `password` (object): EGIS password; masked in answers, the mask or an empty value keeps the stored one. (max length 40)
  - `enabled` (boolean): At least one catalog source is enabled.
  - `infinigate` (InfinigateConfig)
    - `apiKey` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `baseUrl` (string): Base URL of the API; empty uses the default.
    - `clientId` (string): OAuth client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `enabled` (boolean): Search and order through the Infinigate API.
    - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Infinigate are sent through the Infinigate API (off by default; not available yet).
    - `testMode` (boolean): Use the Infinigate test environment.
  - `ingram` (IngramCatalogConfig)
    - `baseUrl` (string): Base URL of the API; empty uses the default.
    - `clientId` (string): OAuth client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `countryCode` (string): Ingram Micro country of the account (ISO 3166-1 alpha-2).
    - `customerNumber` (string): Ingram Micro customer number of the tenant.
    - `enabled` (boolean): Search and order through the Ingram Micro API.
    - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Ingram Micro are sent through the Ingram API (off by default).
    - `sandbox` (boolean): Use the sandbox environment.
  - `lastSync` (string (date-time)): When the catalog was last synchronised.
  - `manufacturerMappings` (array of ManufacturerMapping): Manufacturer names and aliases mapped to masterdata manufacturer codes.
    - `aliases` (array of string): Other spellings of the manufacturer in the distributor catalogs.
    - `code` (string): Manufacturer code in masterdata.
    - `id` (string): Id of the mapping.
    - `name` (string): Manufacturer name in masterdata.
  - `syncIntervalCron` (string): Cron expression of the catalog sync.
- `lastEditor` (string, read-only): Who saved the configuration last.
- `lastUpdate` (string (date-time), read-only): When the configuration was last saved.
- `mail` (object): Mail settings.
  - `channelId` (string): Comms mail channel for invoice mails; the tenant default when empty.
- `msp` (TradeMSPConfig)
  - `autoBilling` (object): Window in the month after the billed one in which the drafts are approved without a person, once every active connector collected the month and no subscription lacks a customer or an article: at `from` when nothing blocks, else at every recheck and right after a collection ended, until `to`. When enabled, `from` must lie before `to` and every enabled connector's schedule before `to` (422 otherwise).
    - `enabled` (boolean): Bill the month automatically.
    - `from` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
    - `recheckHours` (integer): Hours until a blocked month (a connector missing, subscriptions without customer or article) is checked again; empty: 4. (max 168)
    - `to` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
  - `enabled` (boolean): MSP billing is on.
  - `ingram` (object): Ingram Micro cloud subscriptions (Microsoft CSP included), read through the Reseller API v7 with the Ingram connection of the distributor settings (`itsp.ingram`). The end customers (details, Custom_Account_ID = our address number) are read from the Cloud Marketplace API with the `marketplace*` access below; optional, without it customers are matched by name only.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Microsoft articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Microsoft articles MSP billing creates for subscriptions without article; without unit and product group none is created.
    - `enabled` (boolean): Collect Ingram Micro marketplace usage.
    - `marketplaceCode` (string): Marketplace code.
    - `marketplaceLogin` (string): Ingram Micro marketplace login.
    - `marketplacePassword` (object): Write-only: stored encrypted, masked in answers; send the mask back to keep it.
    - `marketplaceSubscriptionKey` (object): Subscription key (`X-Subscription-Key`). Write-only: stored encrypted, masked in answers.
    - `marketplaceUrl` (string): Base URL of the Cloud Marketplace API gateway.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `ingram`). Also the supplier of the Microsoft articles MSP billing creates.
  - `itc` (object): ITC Riemer (provider `itc`): no API, its monthly reports are uploaded (`uploadMspItcReport`) and count for the completeness of the month without a schedule.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the ITC articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the ITC articles MSP billing creates for SKUs without article; without unit and product group none is created.
    - `enabled` (boolean): Bill ITC Riemer reports.
    - `supplierAddressId` (string): Masterdata address of ITC Riemer: uploaded reports are filed under it in DMS, it is the supplier of the ITC articles MSP billing creates and the reconciliation compares its inbound invoices.
  - `mailstore` (object): MailStore connection.
    - `enabled` (boolean): Collect MailStore usage.
    - `password` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `schedule` (object): When the previous month is collected each month.
    - `supplierAddressId` (string): Masterdata address of the supplier whose inbound invoices the reconciliation compares; empty: the address linked with the distributor id `mailstore`.
    - `url` (string): URL of the MailStore SPE.
    - `username` (string): MailStore user name.
  - `notify` (object): Who is told about the connector runs and the automatic billing.
    - `recipients` (array of string (email)): E-mail addresses; trimmed, empty and repeated ones dropped.
  - `sophos` (object): Sophos connection.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Sophos articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Sophos articles MSP billing creates from the Infinigate catalog for SKUs without article; without unit and product group none is created.
    - `clientId` (string): Sophos API client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `enabled` (boolean): Collect Sophos usage.
    - `partnerId` (string): Sophos partner id.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `sophos`). Also the supplier of the Sophos articles MSP billing creates (else the address of the distributor id `infinigate`).
  - `taxRate` (number): VAT rate of the MSP invoices in percent; empty: 19. (max 100)
- `outbound` (object): Outgoing document settings.
  - `defaultPaymentTerms` (string): Payment term code used when the partner has none.
  - `defaultTaxKey` (string): Default tax key of outgoing documents.
  - `dunningEnabled` (boolean): Dunning is on.
  - `eInvoiceMicrotechCheck` (boolean): Validate the e-invoices of invoices and credit notes booked in microtech in the background (results: `listInvoiceValidations` with `source=microtech`).
  - `eInvoiceValidation` (string): What an invalid e-invoice does to an issued invoice: `warn` (default) issues it and raises `trade.invoice.validation_failed`, `block` refuses it with 422 `einvoice_invalid`. (one of `warn`, `block`)
  - `numberRangeRef` (string): Number range of the outgoing documents.
  - `offerTokenValidityDays` (integer): Days an offer link stays valid.
- `procurement` (TradeProcurementConfig): Purchasing settings (purchase recommendations, carts, cart optimizer). Every field is optional.
  - `allowSplit` (boolean): Let the optimizer split a cart line across distributors. (default `true`)
  - `autoCart` (boolean): Put every newly opened purchase recommendation into the automatic cart. It never optimizes or orders by itself. (default `false`)
  - `distributors` (object): Cost model per offer key `<source>:<distributorId>` (e.g. `egis:4711`, `masterdata:<supplierAddressId>`), used when the distributor API quotes no shipping cost.
  - `excluded` (array of string): Offer keys the optimizer never uses.
  - `includeMasterdataPrices` (boolean): Use the supplier prices of masterdata articles as offers (availability unknown). (default `true`)
  - `offerTtlMinutes` (integer): How long gathered offers and a proposal built from them stay valid; 0 = 15. (default `15`)
  - `preferred` (array of string): Offer keys that win a tie.

Example 200 answer:

```json
{
  "active": true,
  "ai": {
    "enabledFeatures": [
      "inbound_extraction",
      "delivery_note_extraction"
    ]
  },
  "inbound": {
    "autoGoodsReceipt": {
      "minConfidence": 0.9,
      "mode": "dryRun"
    },
    "autoRelease": {
      "excludedSupplierIds": [
        "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d07"
      ],
      "maxGrossEur": 2500,
      "minReleasedInvoices": 3,
      "mode": "dryRun",
      "supplierIds": []
    },
    "fallbackVendorNo": "79999",
    "ignoredArticles": [
      "VERSAND",
      "FRACHT"
    ],
    "lastRagSync": "2026-11-19T02:00:00Z",
    "matching": {
      "allowQuantityOverhang": false,
      "maxPriceVarianceAbs": 2,
      "maxPriceVariancePercent": 1
    },
    "recipientCity": "Regensburg",
    "recipientCountry": "DE",
    "recipientIban": "DE02120300000000202051",
    "recipientName": "Muster IT-Systemhaus GmbH",
    "recipientStreet": "Industriestraße 12",
    "recipientVatId": "DE999000111",
    "recipientZip": "93055",
    "strictEInvoice": false
  },
  "itsp": {
    "aiEnrichment": {
      "enabled": true,
      "model": ""
    },
    "amazon": {
      "baseUrl": "",
      "clientId": "",
      "clientSecret": "",
      "enabled": false,
      "locale": "de_DE",
      "refreshToken": "",
      "region": "EU",
      "sandbox": false,
      "userEmail": ""
    },
    "egis": {
      "baseUrl": "",
      "enabled": true,
      "erp": "ConnectCloud",
      "login": "EXAMPLE-egis-login",
      "password": "••••••••"
    },
    "enabled": true,
    "infinigate": {
      "apiKey": "••••••••",
      "baseUrl": "",
      "clientId": "EXAMPLE-infinigate-client-id",
      "clientSecret": "••••••••",
      "enabled": true,
      "orderingEnabled": false,
      "testMode": false
    },
    "ingram": {
      "baseUrl": "",
      "clientId": "EXAMPLE-ingram-client-id",
      "clientSecret": "••••••••",
      "countryCode": "DE",
      "customerNumber": "EXAMPLE-20-123456",
      "enabled": true,
      "orderingEnabled": true,
      "sandbox": false
    },
    "manufacturerMappings": [
      {
        "aliases": [
          "HP Enterprise",
          "HPE Aruba"
        ],
        "code": "HPE",
        "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b01",
        "name": "Hewlett Packard Enterprise"
      },
      {
        "aliases": [
          "Lenovo Global Technology",
          "LENOVO DCG"
        ],
        "code": "LNV",
        "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b02",
        "name": "Lenovo"
      }
    ]
  },
  "lastEditor": "laura.kaestner@muster-it.example",
  "lastUpdate": "2026-11-18T15:40:00Z",
  "mail": {
    "channelId": ""
  },
  "msp": {
    "autoBilling": {
      "enabled": true,
      "from": {
        "day": 5,
        "time": "06:00"
      },
      "recheckHours": 4,
      "to": {
        "day": 10,
        "time": "17:00"
      }
    },
    "enabled": true,
    "ingram": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "enabled": true,
      "marketplaceCode": "de",
      "marketplaceLogin": "EXAMPLE-marketplace-login",
      "marketplacePassword": "••••••••",
      "marketplaceSubscriptionKey": "••••••••",
      "marketplaceUrl": "https://marketplace.ingram.example",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"
    },
    "itc": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05",
      "articleUnitCode": "MON",
      "enabled": true,
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"
    },
    "mailstore": {
      "enabled": true,
      "password": "••••••••",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "",
      "url": "https://mailstore.muster-it.example:8474",
      "username": "EXAMPLE-api-user"
    },
    "notify": {
      "recipients": [
        "laura.kaestner@muster-it.example",
        "christina.adler@muster-it.example"
      ]
    },
    "sophos": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "clientId": "EXAMPLE-sophos-client-id",
      "clientSecret": "••••••••",
      "enabled": true,
      "partnerId": "EXAMPLE-sophos-partner-id",
      "schedule": {
        "day": 2,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"
    },
    "taxRate": 19
  },
  "outbound": {
    "defaultPaymentTerms": "NETTO14",
    "defaultTaxKey": "STANDARD",
    "dunningEnabled": false,
    "eInvoiceMicrotechCheck": false,
    "eInvoiceValidation": "warn",
    "numberRangeRef": "",
    "offerTokenValidityDays": 30
  },
  "procurement": {
    "allowSplit": true,
    "autoCart": true,
    "distributors": {
      "egis:70044": {
        "defaultDeliveryDays": 1,
        "dropShipFee": 7.5,
        "freeShippingFrom": 1500,
        "minOrderSurcharge": 10,
        "minOrderValue": 50,
        "shippingCost": 8.5
      },
      "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02": {
        "defaultDeliveryDays": 2,
        "dropShipFee": 0,
        "freeShippingFrom": 500,
        "minOrderSurcharge": 0,
        "minOrderValue": 0,
        "shippingCost": 12
      }
    },
    "excluded": [],
    "includeMasterdataPrices": true,
    "offerTtlMinutes": 15,
    "preferred": [
      "egis:70044"
    ]
  }
}
```

### Example request

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

## Replace the trade configuration (tenant:settings:write)

`PUT /api/trade/v1/config`

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

Replaces the whole configuration; masked or empty secrets keep their stored value. `lastUpdate` and `lastEditor` are set by the server. `422` also covers an invalid `msp` section (schedule day 1–28 or time `HH:MM`, automatic billing window, tax rate, notification addresses).

### Request body

`application/json` (required)

- `active` (boolean): Trade is active for the tenant.
- `ai` (object): AI settings.
  - `enabledFeatures` (array of string): AI features turned on.
- `inbound` (object): Inbound invoice settings.
  - `autoGoodsReceipt` (AutoGoodsReceiptConfig): Automatic goods receipt for supplier delivery notes whose lines match the open quantities of their purchase order exactly. A note read by AI must also deliver every open line of the order (a partial delivery of the order waits for a person); an EGIS note posts per shipment. Off by default.
    - `minConfidence` (number): Extraction confidence a delivery note needs unless it comes from EGIS (default 0.9).
    - `mode` (string): `off` (default), `dryRun` or `on`. (one of `off`, `dryRun`, `on`)
  - `autoRelease` (AutoReleaseConfig): Automatic release of inbound invoices with a clean 3-way match. Off by default.
    - `excludedSupplierIds` (array of string (uuid)): Supplier addresses that never release themselves; wins over `supplierIds` and history.
    - `maxGrossEur` (number): Highest gross EUR amount that releases itself; required above 0 when the mode is not `off`.
    - `minReleasedInvoices` (integer): Released invoices a supplier needs before it is trusted (default 3).
    - `mode` (string): `off` (default) stores nothing, `dryRun` only stores the verdict (`InboundInvoice.autoRelease`), `on` releases eligible invoices in the transaction that matches them. (one of `off`, `dryRun`, `on`)
    - `supplierIds` (array of string (uuid)): Supplier addresses trusted without history; optional.
  - `fallbackVendorNo` (string): Supplier number used when no supplier is found.
  - `ignoredArticles` (array of string): Article numbers the matching ignores (e.g. freight).
  - `lastRagSync` (string (date-time)): When suppliers and articles were last indexed for matching.
  - `matching` (MatchingTolerances)
    - `allowQuantityOverhang` (boolean): Accept invoiced quantities above the received ones.
    - `maxPriceVarianceAbs` (number): Highest accepted unit price variance as amount (e.g. 2.00 EUR).
    - `maxPriceVariancePercent` (number): Highest accepted unit price variance in percent (1.0 = 1 %).
  - `recipientCity` (string): City of the tenant as invoice recipient.
  - `recipientCountry` (string): Country of the tenant as invoice recipient.
  - `recipientIban` (string): IBAN of the tenant.
  - `recipientName` (string): Our company as invoice recipient (checked on inbound invoices).
  - `recipientStreet` (string): Street of the tenant as invoice recipient.
  - `recipientVatId` (string): VAT id of the tenant as invoice recipient.
  - `recipientZip` (string): Postal code of the tenant as invoice recipient.
  - `strictEInvoice` (boolean): Block invoices without structured XML.
- `itsp` (object): Distributor catalog settings.
  - `aiEnrichment` (AIEnrichmentConfig): Null until saved once.
    - `enabled` (boolean): Propose article texts and product groups with AI.
    - `model` (string): AI model of the enrichment; empty uses the default.
  - `amazon` (AmazonConfig)
    - `baseUrl` (string): Base URL of the API; empty uses the default.
    - `clientId` (string): OAuth client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `enabled` (boolean): Search the Amazon Business catalog.
    - `locale` (string): Locale of the product data (e.g. `de_DE`).
    - `refreshToken` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `region` (string): Amazon region of the account.
    - `sandbox` (boolean): Use the sandbox environment.
    - `userEmail` (string): E-mail of the Amazon Business user the searches run as.
  - `apiKeyId` (string): API key id of the catalog service.
  - `apiKeySecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `baseUrl` (string): Base URL of the catalog service.
  - `customerId` (string): Customer id at the catalog service.
  - `defaultCountryCode` (string): Default country of the catalog searches.
  - `egis` (EgisConfig)
    - `baseUrl` (string): Base URL of the API; empty uses the default.
    - `enabled` (boolean): Search and order through EGIS.
    - `erp` (string): ERP name sent to EGIS; empty uses the default.
    - `login` (string): EGIS login. (max length 40)
    - `password` (object): EGIS password; masked in answers, the mask or an empty value keeps the stored one. (max length 40)
  - `enabled` (boolean): At least one catalog source is enabled.
  - `infinigate` (InfinigateConfig)
    - `apiKey` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `baseUrl` (string): Base URL of the API; empty uses the default.
    - `clientId` (string): OAuth client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `enabled` (boolean): Search and order through the Infinigate API.
    - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Infinigate are sent through the Infinigate API (off by default; not available yet).
    - `testMode` (boolean): Use the Infinigate test environment.
  - `ingram` (IngramCatalogConfig)
    - `baseUrl` (string): Base URL of the API; empty uses the default.
    - `clientId` (string): OAuth client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `countryCode` (string): Ingram Micro country of the account (ISO 3166-1 alpha-2).
    - `customerNumber` (string): Ingram Micro customer number of the tenant.
    - `enabled` (boolean): Search and order through the Ingram Micro API.
    - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Ingram Micro are sent through the Ingram API (off by default).
    - `sandbox` (boolean): Use the sandbox environment.
  - `lastSync` (string (date-time)): When the catalog was last synchronised.
  - `manufacturerMappings` (array of ManufacturerMapping): Manufacturer names and aliases mapped to masterdata manufacturer codes.
    - `aliases` (array of string): Other spellings of the manufacturer in the distributor catalogs.
    - `code` (string): Manufacturer code in masterdata.
    - `id` (string): Id of the mapping.
    - `name` (string): Manufacturer name in masterdata.
  - `syncIntervalCron` (string): Cron expression of the catalog sync.
- `lastEditor` (string, read-only): Who saved the configuration last.
- `lastUpdate` (string (date-time), read-only): When the configuration was last saved.
- `mail` (object): Mail settings.
  - `channelId` (string): Comms mail channel for invoice mails; the tenant default when empty.
- `msp` (TradeMSPConfig)
  - `autoBilling` (object): Window in the month after the billed one in which the drafts are approved without a person, once every active connector collected the month and no subscription lacks a customer or an article: at `from` when nothing blocks, else at every recheck and right after a collection ended, until `to`. When enabled, `from` must lie before `to` and every enabled connector's schedule before `to` (422 otherwise).
    - `enabled` (boolean): Bill the month automatically.
    - `from` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
    - `recheckHours` (integer): Hours until a blocked month (a connector missing, subscriptions without customer or article) is checked again; empty: 4. (max 168)
    - `to` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
  - `enabled` (boolean): MSP billing is on.
  - `ingram` (object): Ingram Micro cloud subscriptions (Microsoft CSP included), read through the Reseller API v7 with the Ingram connection of the distributor settings (`itsp.ingram`). The end customers (details, Custom_Account_ID = our address number) are read from the Cloud Marketplace API with the `marketplace*` access below; optional, without it customers are matched by name only.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Microsoft articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Microsoft articles MSP billing creates for subscriptions without article; without unit and product group none is created.
    - `enabled` (boolean): Collect Ingram Micro marketplace usage.
    - `marketplaceCode` (string): Marketplace code.
    - `marketplaceLogin` (string): Ingram Micro marketplace login.
    - `marketplacePassword` (object): Write-only: stored encrypted, masked in answers; send the mask back to keep it.
    - `marketplaceSubscriptionKey` (object): Subscription key (`X-Subscription-Key`). Write-only: stored encrypted, masked in answers.
    - `marketplaceUrl` (string): Base URL of the Cloud Marketplace API gateway.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `ingram`). Also the supplier of the Microsoft articles MSP billing creates.
  - `itc` (object): ITC Riemer (provider `itc`): no API, its monthly reports are uploaded (`uploadMspItcReport`) and count for the completeness of the month without a schedule.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the ITC articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the ITC articles MSP billing creates for SKUs without article; without unit and product group none is created.
    - `enabled` (boolean): Bill ITC Riemer reports.
    - `supplierAddressId` (string): Masterdata address of ITC Riemer: uploaded reports are filed under it in DMS, it is the supplier of the ITC articles MSP billing creates and the reconciliation compares its inbound invoices.
  - `mailstore` (object): MailStore connection.
    - `enabled` (boolean): Collect MailStore usage.
    - `password` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `schedule` (object): When the previous month is collected each month.
    - `supplierAddressId` (string): Masterdata address of the supplier whose inbound invoices the reconciliation compares; empty: the address linked with the distributor id `mailstore`.
    - `url` (string): URL of the MailStore SPE.
    - `username` (string): MailStore user name.
  - `notify` (object): Who is told about the connector runs and the automatic billing.
    - `recipients` (array of string (email)): E-mail addresses; trimmed, empty and repeated ones dropped.
  - `sophos` (object): Sophos connection.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Sophos articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Sophos articles MSP billing creates from the Infinigate catalog for SKUs without article; without unit and product group none is created.
    - `clientId` (string): Sophos API client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `enabled` (boolean): Collect Sophos usage.
    - `partnerId` (string): Sophos partner id.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `sophos`). Also the supplier of the Sophos articles MSP billing creates (else the address of the distributor id `infinigate`).
  - `taxRate` (number): VAT rate of the MSP invoices in percent; empty: 19. (max 100)
- `outbound` (object): Outgoing document settings.
  - `defaultPaymentTerms` (string): Payment term code used when the partner has none.
  - `defaultTaxKey` (string): Default tax key of outgoing documents.
  - `dunningEnabled` (boolean): Dunning is on.
  - `eInvoiceMicrotechCheck` (boolean): Validate the e-invoices of invoices and credit notes booked in microtech in the background (results: `listInvoiceValidations` with `source=microtech`).
  - `eInvoiceValidation` (string): What an invalid e-invoice does to an issued invoice: `warn` (default) issues it and raises `trade.invoice.validation_failed`, `block` refuses it with 422 `einvoice_invalid`. (one of `warn`, `block`)
  - `numberRangeRef` (string): Number range of the outgoing documents.
  - `offerTokenValidityDays` (integer): Days an offer link stays valid.
- `procurement` (TradeProcurementConfig): Purchasing settings (purchase recommendations, carts, cart optimizer). Every field is optional.
  - `allowSplit` (boolean): Let the optimizer split a cart line across distributors. (default `true`)
  - `autoCart` (boolean): Put every newly opened purchase recommendation into the automatic cart. It never optimizes or orders by itself. (default `false`)
  - `distributors` (object): Cost model per offer key `<source>:<distributorId>` (e.g. `egis:4711`, `masterdata:<supplierAddressId>`), used when the distributor API quotes no shipping cost.
  - `excluded` (array of string): Offer keys the optimizer never uses.
  - `includeMasterdataPrices` (boolean): Use the supplier prices of masterdata articles as offers (availability unknown). (default `true`)
  - `offerTtlMinutes` (integer): How long gathered offers and a proposal built from them stay valid; 0 = 15. (default `15`)
  - `preferred` (array of string): Offer keys that win a tie.

Example:

```json
{
  "active": true,
  "ai": {
    "enabledFeatures": [
      "inbound_extraction",
      "delivery_note_extraction"
    ]
  },
  "inbound": {
    "autoGoodsReceipt": {
      "minConfidence": 0.9,
      "mode": "dryRun"
    },
    "autoRelease": {
      "excludedSupplierIds": [
        "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d07"
      ],
      "maxGrossEur": 2500,
      "minReleasedInvoices": 3,
      "mode": "dryRun",
      "supplierIds": []
    },
    "fallbackVendorNo": "79999",
    "ignoredArticles": [
      "VERSAND",
      "FRACHT"
    ],
    "lastRagSync": "2026-11-19T02:00:00Z",
    "matching": {
      "allowQuantityOverhang": false,
      "maxPriceVarianceAbs": 2,
      "maxPriceVariancePercent": 1
    },
    "recipientCity": "Regensburg",
    "recipientCountry": "DE",
    "recipientIban": "DE02120300000000202051",
    "recipientName": "Muster IT-Systemhaus GmbH",
    "recipientStreet": "Industriestraße 12",
    "recipientVatId": "DE999000111",
    "recipientZip": "93055",
    "strictEInvoice": false
  },
  "itsp": {
    "aiEnrichment": {
      "enabled": true,
      "model": ""
    },
    "amazon": {
      "baseUrl": "",
      "clientId": "",
      "clientSecret": "",
      "enabled": false,
      "locale": "de_DE",
      "refreshToken": "",
      "region": "EU",
      "sandbox": false,
      "userEmail": ""
    },
    "egis": {
      "baseUrl": "",
      "enabled": true,
      "erp": "ConnectCloud",
      "login": "EXAMPLE-egis-login",
      "password": "••••••••"
    },
    "enabled": true,
    "infinigate": {
      "apiKey": "••••••••",
      "baseUrl": "",
      "clientId": "EXAMPLE-infinigate-client-id",
      "clientSecret": "••••••••",
      "enabled": true,
      "orderingEnabled": false,
      "testMode": false
    },
    "ingram": {
      "baseUrl": "",
      "clientId": "EXAMPLE-ingram-client-id",
      "clientSecret": "••••••••",
      "countryCode": "DE",
      "customerNumber": "EXAMPLE-20-123456",
      "enabled": true,
      "orderingEnabled": true,
      "sandbox": false
    },
    "manufacturerMappings": [
      {
        "aliases": [
          "HP Enterprise",
          "HPE Aruba"
        ],
        "code": "HPE",
        "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b01",
        "name": "Hewlett Packard Enterprise"
      },
      {
        "aliases": [
          "Lenovo Global Technology",
          "LENOVO DCG"
        ],
        "code": "LNV",
        "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b02",
        "name": "Lenovo"
      }
    ]
  },
  "lastEditor": "laura.kaestner@muster-it.example",
  "lastUpdate": "2026-11-18T15:40:00Z",
  "mail": {
    "channelId": ""
  },
  "msp": {
    "autoBilling": {
      "enabled": true,
      "from": {
        "day": 5,
        "time": "06:00"
      },
      "recheckHours": 4,
      "to": {
        "day": 10,
        "time": "17:00"
      }
    },
    "enabled": true,
    "ingram": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "enabled": true,
      "marketplaceCode": "de",
      "marketplaceLogin": "EXAMPLE-marketplace-login",
      "marketplacePassword": "••••••••",
      "marketplaceSubscriptionKey": "••••••••",
      "marketplaceUrl": "https://marketplace.ingram.example",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"
    },
    "itc": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05",
      "articleUnitCode": "MON",
      "enabled": true,
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"
    },
    "mailstore": {
      "enabled": true,
      "password": "••••••••",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "",
      "url": "https://mailstore.muster-it.example:8474",
      "username": "EXAMPLE-api-user"
    },
    "notify": {
      "recipients": [
        "laura.kaestner@muster-it.example",
        "christina.adler@muster-it.example"
      ]
    },
    "sophos": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "clientId": "EXAMPLE-sophos-client-id",
      "clientSecret": "••••••••",
      "enabled": true,
      "partnerId": "EXAMPLE-sophos-partner-id",
      "schedule": {
        "day": 2,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"
    },
    "taxRate": 19
  },
  "outbound": {
    "defaultPaymentTerms": "NETTO14",
    "defaultTaxKey": "STANDARD",
    "dunningEnabled": false,
    "eInvoiceMicrotechCheck": false,
    "eInvoiceValidation": "warn",
    "numberRangeRef": "",
    "offerTokenValidityDays": 30
  },
  "procurement": {
    "allowSplit": true,
    "autoCart": true,
    "distributors": {
      "egis:70044": {
        "defaultDeliveryDays": 1,
        "dropShipFee": 7.5,
        "freeShippingFrom": 1500,
        "minOrderSurcharge": 10,
        "minOrderValue": 50,
        "shippingCost": 8.5
      },
      "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02": {
        "defaultDeliveryDays": 2,
        "dropShipFee": 0,
        "freeShippingFrom": 500,
        "minOrderSurcharge": 0,
        "minOrderValue": 0,
        "shippingCost": 12
      }
    },
    "excluded": [],
    "includeMasterdataPrices": true,
    "offerTtlMinutes": 15,
    "preferred": [
      "egis:70044"
    ]
  }
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** The input is not valid for the stored data. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `status` (string, required): Outcome of the request.

Example 200 answer:

```json
{
  "status": "saved"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/config' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true,"ai":{"enabledFeatures":["inbound_extraction","delivery_note_extraction"]},"inbound":{"autoGoodsReceipt":{"minConfidence":0.9,"mode":"dryRun"},"autoRelease":{"excludedSupplierIds":["6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d07"],"maxGrossEur":2500,"minReleasedInvoices":3,"mode":"dryRun","supplierIds":[]},"fallbackVendorNo":"79999","ignoredArticles":["VERSAND","FRACHT"],"lastRagSync":"2026-11-19T02:00:00Z","matching":{"allowQuantityOverhang":false,"maxPriceVarianceAbs":2,"maxPriceVariancePercent":1},"recipientCity":"Regensburg","recipientCountry":"DE","recipientIban":"DE02120300000000202051","recipientName":"Muster IT-Systemhaus GmbH","recipientStreet":"Industriestraße 12","recipientVatId":"DE999000111","recipientZip":"93055","strictEInvoice":false},"itsp":{"aiEnrichment":{"enabled":true,"model":""},"amazon":{"baseUrl":"","clientId":"","clientSecret":"","enabled":false,"locale":"de_DE","refreshToken":"","region":"EU","sandbox":false,"userEmail":""},"egis":{"baseUrl":"","enabled":true,"erp":"ConnectCloud","login":"EXAMPLE-egis-login","password":"••••••••"},"enabled":true,"infinigate":{"apiKey":"••••••••","baseUrl":"","clientId":"EXAMPLE-infinigate-client-id","clientSecret":"••••••••","enabled":true,"orderingEnabled":false,"testMode":false},"ingram":{"baseUrl":"","clientId":"EXAMPLE-ingram-client-id","clientSecret":"••••••••","countryCode":"DE","customerNumber":"EXAMPLE-20-123456","enabled":true,"orderingEnabled":true,"sandbox":false},"manufacturerMappings":[{"aliases":["HP Enterprise","HPE Aruba"],"code":"HPE","id":"7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b01","name":"Hewlett Packard Enterprise"},{"aliases":["Lenovo Global Technology","LENOVO DCG"],"code":"LNV","id":"7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b02","name":"Lenovo"}]},"lastEditor":"laura.kaestner@muster-it.example","lastUpdate":"2026-11-18T15:40:00Z","mail":{"channelId":""},"msp":{"autoBilling":{"enabled":true,"from":{"day":5,"time":"06:00"},"recheckHours":4,"to":{"day":10,"time":"17:00"}},"enabled":true,"ingram":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04","articleUnitCode":"LIZ","enabled":true,"marketplaceCode":"de","marketplaceLogin":"EXAMPLE-marketplace-login","marketplacePassword":"••••••••","marketplaceSubscriptionKey":"••••••••","marketplaceUrl":"https://marketplace.ingram.example","schedule":{"day":1,"time":"06:00"},"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"},"itc":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05","articleUnitCode":"MON","enabled":true,"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"},"mailstore":{"enabled":true,"password":"••••••••","schedule":{"day":1,"time":"06:00"},"supplierAddressId":"","url":"https://mailstore.muster-it.example:8474","username":"EXAMPLE-api-user"},"notify":{"recipients":["laura.kaestner@muster-it.example","christina.adler@muster-it.example"]},"sophos":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04","articleUnitCode":"LIZ","clientId":"EXAMPLE-sophos-client-id","clientSecret":"••••••••","enabled":true,"partnerId":"EXAMPLE-sophos-partner-id","schedule":{"day":2,"time":"06:00"},"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"},"taxRate":19},"outbound":{"defaultPaymentTerms":"NETTO14","defaultTaxKey":"STANDARD","dunningEnabled":false,"eInvoiceMicrotechCheck":false,"eInvoiceValidation":"warn","numberRangeRef":"","offerTokenValidityDays":30},"procurement":{"allowSplit":true,"autoCart":true,"distributors":{"egis:70044":{"defaultDeliveryDays":1,"dropShipFee":7.5,"freeShippingFrom":1500,"minOrderSurcharge":10,"minOrderValue":50,"shippingCost":8.5},"masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02":{"defaultDeliveryDays":2,"dropShipFee":0,"freeShippingFrom":500,"minOrderSurcharge":0,"minOrderValue":0,"shippingCost":12}},"excluded":[],"includeMasterdataPrices":true,"offerTtlMinutes":15,"preferred":["egis:70044"]}}'
```

## Whether trade is active for the tenant (signed in)

`GET /api/trade/v1/config/status`

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

### Responses

- **200** Status (`application/json`)
- **401** No valid session or bearer token (no body).
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `active` (boolean, required)

Example 200 answer:

```json
{
  "active": true
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/config/status' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get the MSP billing configuration (tenant:settings:read)

`GET /api/trade/v1/msp/config`

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

The `msp` section of the configuration; secrets are masked.

### Responses

- **200** MSP configuration (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `autoBilling` (object): Window in the month after the billed one in which the drafts are approved without a person, once every active connector collected the month and no subscription lacks a customer or an article: at `from` when nothing blocks, else at every recheck and right after a collection ended, until `to`. When enabled, `from` must lie before `to` and every enabled connector's schedule before `to` (422 otherwise).
  - `enabled` (boolean): Bill the month automatically.
  - `from` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
    - `day` (integer): Day of the month (1–28). (max 28)
    - `time` (string): `HH:MM`, 24 h.
  - `recheckHours` (integer): Hours until a blocked month (a connector missing, subscriptions without customer or article) is checked again; empty: 4. (max 168)
  - `to` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
    - `day` (integer): Day of the month (1–28). (max 28)
    - `time` (string): `HH:MM`, 24 h.
- `enabled` (boolean): MSP billing is on.
- `ingram` (object): Ingram Micro cloud subscriptions (Microsoft CSP included), read through the Reseller API v7 with the Ingram connection of the distributor settings (`itsp.ingram`). The end customers (details, Custom_Account_ID = our address number) are read from the Cloud Marketplace API with the `marketplace*` access below; optional, without it customers are matched by name only.
  - `articleProductGroupId` (string (uuid)): Masterdata product group of the Microsoft articles MSP billing creates (see `articleUnitCode`).
  - `articleUnitCode` (string): Masterdata unit code of the Microsoft articles MSP billing creates for subscriptions without article; without unit and product group none is created.
  - `enabled` (boolean): Collect Ingram Micro marketplace usage.
  - `marketplaceCode` (string): Marketplace code.
  - `marketplaceLogin` (string): Ingram Micro marketplace login.
  - `marketplacePassword` (object): Write-only: stored encrypted, masked in answers; send the mask back to keep it.
  - `marketplaceSubscriptionKey` (object): Subscription key (`X-Subscription-Key`). Write-only: stored encrypted, masked in answers.
  - `marketplaceUrl` (string): Base URL of the Cloud Marketplace API gateway.
  - `schedule` (object): See `mailstore`.
  - `supplierAddressId` (string): See `mailstore` (distributor id `ingram`). Also the supplier of the Microsoft articles MSP billing creates.
- `itc` (object): ITC Riemer (provider `itc`): no API, its monthly reports are uploaded (`uploadMspItcReport`) and count for the completeness of the month without a schedule.
  - `articleProductGroupId` (string (uuid)): Masterdata product group of the ITC articles MSP billing creates (see `articleUnitCode`).
  - `articleUnitCode` (string): Masterdata unit code of the ITC articles MSP billing creates for SKUs without article; without unit and product group none is created.
  - `enabled` (boolean): Bill ITC Riemer reports.
  - `supplierAddressId` (string): Masterdata address of ITC Riemer: uploaded reports are filed under it in DMS, it is the supplier of the ITC articles MSP billing creates and the reconciliation compares its inbound invoices.
- `mailstore` (object): MailStore connection.
  - `enabled` (boolean): Collect MailStore usage.
  - `password` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `schedule` (object): When the previous month is collected each month.
  - `supplierAddressId` (string): Masterdata address of the supplier whose inbound invoices the reconciliation compares; empty: the address linked with the distributor id `mailstore`.
  - `url` (string): URL of the MailStore SPE.
  - `username` (string): MailStore user name.
- `notify` (object): Who is told about the connector runs and the automatic billing.
  - `recipients` (array of string (email)): E-mail addresses; trimmed, empty and repeated ones dropped.
- `sophos` (object): Sophos connection.
  - `articleProductGroupId` (string (uuid)): Masterdata product group of the Sophos articles MSP billing creates (see `articleUnitCode`).
  - `articleUnitCode` (string): Masterdata unit code of the Sophos articles MSP billing creates from the Infinigate catalog for SKUs without article; without unit and product group none is created.
  - `clientId` (string): Sophos API client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `enabled` (boolean): Collect Sophos usage.
  - `partnerId` (string): Sophos partner id.
  - `schedule` (object): See `mailstore`.
  - `supplierAddressId` (string): See `mailstore` (distributor id `sophos`). Also the supplier of the Sophos articles MSP billing creates (else the address of the distributor id `infinigate`).
- `taxRate` (number): VAT rate of the MSP invoices in percent; empty: 19. (max 100)

Example 200 answer:

```json
{
  "autoBilling": {
    "enabled": true,
    "from": {
      "day": 5,
      "time": "06:00"
    },
    "recheckHours": 4,
    "to": {
      "day": 10,
      "time": "17:00"
    }
  },
  "enabled": true,
  "ingram": {
    "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
    "articleUnitCode": "LIZ",
    "enabled": true,
    "marketplaceCode": "de",
    "marketplaceLogin": "EXAMPLE-marketplace-login",
    "marketplacePassword": "••••••••",
    "marketplaceSubscriptionKey": "••••••••",
    "marketplaceUrl": "https://marketplace.ingram.example",
    "schedule": {
      "day": 1,
      "time": "06:00"
    },
    "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"
  },
  "itc": {
    "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05",
    "articleUnitCode": "MON",
    "enabled": true,
    "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"
  },
  "mailstore": {
    "enabled": true,
    "password": "••••••••",
    "schedule": {
      "day": 1,
      "time": "06:00"
    },
    "supplierAddressId": "",
    "url": "https://mailstore.muster-it.example:8474",
    "username": "EXAMPLE-api-user"
  },
  "notify": {
    "recipients": [
      "laura.kaestner@muster-it.example",
      "christina.adler@muster-it.example"
    ]
  },
  "sophos": {
    "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
    "articleUnitCode": "LIZ",
    "clientId": "EXAMPLE-sophos-client-id",
    "clientSecret": "••••••••",
    "enabled": true,
    "partnerId": "EXAMPLE-sophos-partner-id",
    "schedule": {
      "day": 2,
      "time": "06:00"
    },
    "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"
  },
  "taxRate": 19
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/msp/config' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Replace the MSP billing configuration (tenant:settings:write)

`PUT /api/trade/v1/msp/config`

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

Replaces the `msp` section; the rest of the configuration stays. Masked or empty secrets keep their stored value.

### Request body

`application/json` (required)

- `autoBilling` (object): Window in the month after the billed one in which the drafts are approved without a person, once every active connector collected the month and no subscription lacks a customer or an article: at `from` when nothing blocks, else at every recheck and right after a collection ended, until `to`. When enabled, `from` must lie before `to` and every enabled connector's schedule before `to` (422 otherwise).
  - `enabled` (boolean): Bill the month automatically.
  - `from` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
    - `day` (integer): Day of the month (1–28). (max 28)
    - `time` (string): `HH:MM`, 24 h.
  - `recheckHours` (integer): Hours until a blocked month (a connector missing, subscriptions without customer or article) is checked again; empty: 4. (max 168)
  - `to` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
    - `day` (integer): Day of the month (1–28). (max 28)
    - `time` (string): `HH:MM`, 24 h.
- `enabled` (boolean): MSP billing is on.
- `ingram` (object): Ingram Micro cloud subscriptions (Microsoft CSP included), read through the Reseller API v7 with the Ingram connection of the distributor settings (`itsp.ingram`). The end customers (details, Custom_Account_ID = our address number) are read from the Cloud Marketplace API with the `marketplace*` access below; optional, without it customers are matched by name only.
  - `articleProductGroupId` (string (uuid)): Masterdata product group of the Microsoft articles MSP billing creates (see `articleUnitCode`).
  - `articleUnitCode` (string): Masterdata unit code of the Microsoft articles MSP billing creates for subscriptions without article; without unit and product group none is created.
  - `enabled` (boolean): Collect Ingram Micro marketplace usage.
  - `marketplaceCode` (string): Marketplace code.
  - `marketplaceLogin` (string): Ingram Micro marketplace login.
  - `marketplacePassword` (object): Write-only: stored encrypted, masked in answers; send the mask back to keep it.
  - `marketplaceSubscriptionKey` (object): Subscription key (`X-Subscription-Key`). Write-only: stored encrypted, masked in answers.
  - `marketplaceUrl` (string): Base URL of the Cloud Marketplace API gateway.
  - `schedule` (object): See `mailstore`.
  - `supplierAddressId` (string): See `mailstore` (distributor id `ingram`). Also the supplier of the Microsoft articles MSP billing creates.
- `itc` (object): ITC Riemer (provider `itc`): no API, its monthly reports are uploaded (`uploadMspItcReport`) and count for the completeness of the month without a schedule.
  - `articleProductGroupId` (string (uuid)): Masterdata product group of the ITC articles MSP billing creates (see `articleUnitCode`).
  - `articleUnitCode` (string): Masterdata unit code of the ITC articles MSP billing creates for SKUs without article; without unit and product group none is created.
  - `enabled` (boolean): Bill ITC Riemer reports.
  - `supplierAddressId` (string): Masterdata address of ITC Riemer: uploaded reports are filed under it in DMS, it is the supplier of the ITC articles MSP billing creates and the reconciliation compares its inbound invoices.
- `mailstore` (object): MailStore connection.
  - `enabled` (boolean): Collect MailStore usage.
  - `password` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `schedule` (object): When the previous month is collected each month.
  - `supplierAddressId` (string): Masterdata address of the supplier whose inbound invoices the reconciliation compares; empty: the address linked with the distributor id `mailstore`.
  - `url` (string): URL of the MailStore SPE.
  - `username` (string): MailStore user name.
- `notify` (object): Who is told about the connector runs and the automatic billing.
  - `recipients` (array of string (email)): E-mail addresses; trimmed, empty and repeated ones dropped.
- `sophos` (object): Sophos connection.
  - `articleProductGroupId` (string (uuid)): Masterdata product group of the Sophos articles MSP billing creates (see `articleUnitCode`).
  - `articleUnitCode` (string): Masterdata unit code of the Sophos articles MSP billing creates from the Infinigate catalog for SKUs without article; without unit and product group none is created.
  - `clientId` (string): Sophos API client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `enabled` (boolean): Collect Sophos usage.
  - `partnerId` (string): Sophos partner id.
  - `schedule` (object): See `mailstore`.
  - `supplierAddressId` (string): See `mailstore` (distributor id `sophos`). Also the supplier of the Sophos articles MSP billing creates (else the address of the distributor id `infinigate`).
- `taxRate` (number): VAT rate of the MSP invoices in percent; empty: 19. (max 100)

Example:

```json
{
  "autoBilling": {
    "enabled": true,
    "from": {
      "day": 5,
      "time": "06:00"
    },
    "recheckHours": 4,
    "to": {
      "day": 10,
      "time": "17:00"
    }
  },
  "enabled": true,
  "ingram": {
    "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
    "articleUnitCode": "LIZ",
    "enabled": true,
    "marketplaceCode": "de",
    "marketplaceLogin": "EXAMPLE-marketplace-login",
    "marketplacePassword": "••••••••",
    "marketplaceSubscriptionKey": "••••••••",
    "marketplaceUrl": "https://marketplace.ingram.example",
    "schedule": {
      "day": 1,
      "time": "06:00"
    },
    "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"
  },
  "itc": {
    "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05",
    "articleUnitCode": "MON",
    "enabled": true,
    "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"
  },
  "mailstore": {
    "enabled": true,
    "password": "••••••••",
    "schedule": {
      "day": 1,
      "time": "06:00"
    },
    "supplierAddressId": "",
    "url": "https://mailstore.muster-it.example:8474",
    "username": "EXAMPLE-api-user"
  },
  "notify": {
    "recipients": [
      "laura.kaestner@muster-it.example",
      "christina.adler@muster-it.example"
    ]
  },
  "sophos": {
    "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
    "articleUnitCode": "LIZ",
    "clientId": "EXAMPLE-sophos-client-id",
    "clientSecret": "••••••••",
    "enabled": true,
    "partnerId": "EXAMPLE-sophos-partner-id",
    "schedule": {
      "day": 2,
      "time": "06:00"
    },
    "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"
  },
  "taxRate": 19
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** The section is invalid: schedule day or time, automatic billing window (`from` must lie before `to`), tax rate, notification addresses. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `status` (string, required): Outcome of the request.

Example 200 answer:

```json
{
  "status": "saved"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/msp/config' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"autoBilling":{"enabled":true,"from":{"day":5,"time":"06:00"},"recheckHours":4,"to":{"day":10,"time":"17:00"}},"enabled":true,"ingram":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04","articleUnitCode":"LIZ","enabled":true,"marketplaceCode":"de","marketplaceLogin":"EXAMPLE-marketplace-login","marketplacePassword":"••••••••","marketplaceSubscriptionKey":"••••••••","marketplaceUrl":"https://marketplace.ingram.example","schedule":{"day":1,"time":"06:00"},"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"},"itc":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05","articleUnitCode":"MON","enabled":true,"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"},"mailstore":{"enabled":true,"password":"••••••••","schedule":{"day":1,"time":"06:00"},"supplierAddressId":"","url":"https://mailstore.muster-it.example:8474","username":"EXAMPLE-api-user"},"notify":{"recipients":["laura.kaestner@muster-it.example","christina.adler@muster-it.example"]},"sophos":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04","articleUnitCode":"LIZ","clientId":"EXAMPLE-sophos-client-id","clientSecret":"••••••••","enabled":true,"partnerId":"EXAMPLE-sophos-partner-id","schedule":{"day":2,"time":"06:00"},"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"},"taxRate":19}'
```

## Get the distributor and MSP connections (tenant:settings:read)

`GET /api/trade/v1/itsp/config`

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

The catalog sources and MSP billing accounts of the configuration; secrets are masked.

### Responses

- **200** Connections (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `active` (boolean, read-only): True while any connection on the page is enabled.
- `aiEnrichment` (AIEnrichmentConfig): Null until saved once.
  - `enabled` (boolean): Propose article texts and product groups with AI.
  - `model` (string): AI model of the enrichment; empty uses the default.
- `amazon` (AmazonConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `enabled` (boolean): Search the Amazon Business catalog.
  - `locale` (string): Locale of the product data (e.g. `de_DE`).
  - `refreshToken` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `region` (string): Amazon region of the account.
  - `sandbox` (boolean): Use the sandbox environment.
  - `userEmail` (string): E-mail of the Amazon Business user the searches run as.
- `egis` (EgisConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `enabled` (boolean): Search and order through EGIS.
  - `erp` (string): ERP name sent to EGIS; empty uses the default.
  - `login` (string): EGIS login. (max length 40)
  - `password` (object): EGIS password; masked in answers, the mask or an empty value keeps the stored one. (max length 40)
- `infinigate` (InfinigateConfig)
  - `apiKey` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `enabled` (boolean): Search and order through the Infinigate API.
  - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Infinigate are sent through the Infinigate API (off by default; not available yet).
  - `testMode` (boolean): Use the Infinigate test environment.
- `ingram` (IngramCatalogConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `countryCode` (string): Ingram Micro country of the account (ISO 3166-1 alpha-2).
  - `customerNumber` (string): Ingram Micro customer number of the tenant.
  - `enabled` (boolean): Search and order through the Ingram Micro API.
  - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Ingram Micro are sent through the Ingram API (off by default).
  - `sandbox` (boolean): Use the sandbox environment.
- `lastEditor` (string, read-only): Who saved the configuration last.
- `lastUpdate` (string (date-time), read-only): When the configuration was last saved.
- `manufacturerMappings` (array of ManufacturerMapping): Manufacturer names and aliases mapped to masterdata manufacturer codes.
  - `aliases` (array of string): Other spellings of the manufacturer in the distributor catalogs.
  - `code` (string): Manufacturer code in masterdata.
  - `id` (string): Id of the mapping.
  - `name` (string): Manufacturer name in masterdata.
- `msp` (TradeMSPConfig)
  - `autoBilling` (object): Window in the month after the billed one in which the drafts are approved without a person, once every active connector collected the month and no subscription lacks a customer or an article: at `from` when nothing blocks, else at every recheck and right after a collection ended, until `to`. When enabled, `from` must lie before `to` and every enabled connector's schedule before `to` (422 otherwise).
    - `enabled` (boolean): Bill the month automatically.
    - `from` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
    - `recheckHours` (integer): Hours until a blocked month (a connector missing, subscriptions without customer or article) is checked again; empty: 4. (max 168)
    - `to` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
  - `enabled` (boolean): MSP billing is on.
  - `ingram` (object): Ingram Micro cloud subscriptions (Microsoft CSP included), read through the Reseller API v7 with the Ingram connection of the distributor settings (`itsp.ingram`). The end customers (details, Custom_Account_ID = our address number) are read from the Cloud Marketplace API with the `marketplace*` access below; optional, without it customers are matched by name only.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Microsoft articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Microsoft articles MSP billing creates for subscriptions without article; without unit and product group none is created.
    - `enabled` (boolean): Collect Ingram Micro marketplace usage.
    - `marketplaceCode` (string): Marketplace code.
    - `marketplaceLogin` (string): Ingram Micro marketplace login.
    - `marketplacePassword` (object): Write-only: stored encrypted, masked in answers; send the mask back to keep it.
    - `marketplaceSubscriptionKey` (object): Subscription key (`X-Subscription-Key`). Write-only: stored encrypted, masked in answers.
    - `marketplaceUrl` (string): Base URL of the Cloud Marketplace API gateway.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `ingram`). Also the supplier of the Microsoft articles MSP billing creates.
  - `itc` (object): ITC Riemer (provider `itc`): no API, its monthly reports are uploaded (`uploadMspItcReport`) and count for the completeness of the month without a schedule.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the ITC articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the ITC articles MSP billing creates for SKUs without article; without unit and product group none is created.
    - `enabled` (boolean): Bill ITC Riemer reports.
    - `supplierAddressId` (string): Masterdata address of ITC Riemer: uploaded reports are filed under it in DMS, it is the supplier of the ITC articles MSP billing creates and the reconciliation compares its inbound invoices.
  - `mailstore` (object): MailStore connection.
    - `enabled` (boolean): Collect MailStore usage.
    - `password` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `schedule` (object): When the previous month is collected each month.
    - `supplierAddressId` (string): Masterdata address of the supplier whose inbound invoices the reconciliation compares; empty: the address linked with the distributor id `mailstore`.
    - `url` (string): URL of the MailStore SPE.
    - `username` (string): MailStore user name.
  - `notify` (object): Who is told about the connector runs and the automatic billing.
    - `recipients` (array of string (email)): E-mail addresses; trimmed, empty and repeated ones dropped.
  - `sophos` (object): Sophos connection.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Sophos articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Sophos articles MSP billing creates from the Infinigate catalog for SKUs without article; without unit and product group none is created.
    - `clientId` (string): Sophos API client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `enabled` (boolean): Collect Sophos usage.
    - `partnerId` (string): Sophos partner id.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `sophos`). Also the supplier of the Sophos articles MSP billing creates (else the address of the distributor id `infinigate`).
  - `taxRate` (number): VAT rate of the MSP invoices in percent; empty: 19. (max 100)

Example 200 answer:

```json
{
  "active": true,
  "aiEnrichment": {
    "enabled": true,
    "model": ""
  },
  "amazon": {
    "baseUrl": "",
    "clientId": "",
    "clientSecret": "",
    "enabled": false,
    "locale": "de_DE",
    "refreshToken": "",
    "region": "EU",
    "sandbox": false,
    "userEmail": ""
  },
  "egis": {
    "baseUrl": "",
    "enabled": true,
    "erp": "ConnectCloud",
    "login": "EXAMPLE-egis-login",
    "password": "••••••••"
  },
  "infinigate": {
    "apiKey": "••••••••",
    "baseUrl": "",
    "clientId": "EXAMPLE-infinigate-client-id",
    "clientSecret": "••••••••",
    "enabled": true,
    "orderingEnabled": false,
    "testMode": false
  },
  "ingram": {
    "baseUrl": "",
    "clientId": "EXAMPLE-ingram-client-id",
    "clientSecret": "••••••••",
    "countryCode": "DE",
    "customerNumber": "EXAMPLE-20-123456",
    "enabled": true,
    "orderingEnabled": true,
    "sandbox": false
  },
  "lastEditor": "laura.kaestner@muster-it.example",
  "lastUpdate": "2026-11-18T15:40:00Z",
  "manufacturerMappings": [
    {
      "aliases": [
        "HP Enterprise",
        "HPE Aruba"
      ],
      "code": "HPE",
      "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b01",
      "name": "Hewlett Packard Enterprise"
    },
    {
      "aliases": [
        "Lenovo Global Technology",
        "LENOVO DCG"
      ],
      "code": "LNV",
      "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b02",
      "name": "Lenovo"
    }
  ],
  "msp": {
    "autoBilling": {
      "enabled": true,
      "from": {
        "day": 5,
        "time": "06:00"
      },
      "recheckHours": 4,
      "to": {
        "day": 10,
        "time": "17:00"
      }
    },
    "enabled": true,
    "ingram": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "enabled": true,
      "marketplaceCode": "de",
      "marketplaceLogin": "EXAMPLE-marketplace-login",
      "marketplacePassword": "••••••••",
      "marketplaceSubscriptionKey": "••••••••",
      "marketplaceUrl": "https://marketplace.ingram.example",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"
    },
    "itc": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05",
      "articleUnitCode": "MON",
      "enabled": true,
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"
    },
    "mailstore": {
      "enabled": true,
      "password": "••••••••",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "",
      "url": "https://mailstore.muster-it.example:8474",
      "username": "EXAMPLE-api-user"
    },
    "notify": {
      "recipients": [
        "laura.kaestner@muster-it.example",
        "christina.adler@muster-it.example"
      ]
    },
    "sophos": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "clientId": "EXAMPLE-sophos-client-id",
      "clientSecret": "••••••••",
      "enabled": true,
      "partnerId": "EXAMPLE-sophos-partner-id",
      "schedule": {
        "day": 2,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"
    },
    "taxRate": 19
  }
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/itsp/config' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Save the distributor and MSP connections (tenant:settings:write)

`PUT /api/trade/v1/itsp/config`

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

Replaces the catalog sources, manufacturer mappings and the `msp` section (`aiEnrichment` only
when sent); `active` and the `enabled` flags of ITSP/MSP are derived. Masked or empty secrets keep
their stored value. EGIS login and password may have at most 40 characters. Answers the saved
configuration. Saving drops cached searches of the tenant.

### Request body

`application/json` (required)

- `active` (boolean, read-only): True while any connection on the page is enabled.
- `aiEnrichment` (AIEnrichmentConfig): Null until saved once.
  - `enabled` (boolean): Propose article texts and product groups with AI.
  - `model` (string): AI model of the enrichment; empty uses the default.
- `amazon` (AmazonConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `enabled` (boolean): Search the Amazon Business catalog.
  - `locale` (string): Locale of the product data (e.g. `de_DE`).
  - `refreshToken` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `region` (string): Amazon region of the account.
  - `sandbox` (boolean): Use the sandbox environment.
  - `userEmail` (string): E-mail of the Amazon Business user the searches run as.
- `egis` (EgisConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `enabled` (boolean): Search and order through EGIS.
  - `erp` (string): ERP name sent to EGIS; empty uses the default.
  - `login` (string): EGIS login. (max length 40)
  - `password` (object): EGIS password; masked in answers, the mask or an empty value keeps the stored one. (max length 40)
- `infinigate` (InfinigateConfig)
  - `apiKey` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `enabled` (boolean): Search and order through the Infinigate API.
  - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Infinigate are sent through the Infinigate API (off by default; not available yet).
  - `testMode` (boolean): Use the Infinigate test environment.
- `ingram` (IngramCatalogConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `countryCode` (string): Ingram Micro country of the account (ISO 3166-1 alpha-2).
  - `customerNumber` (string): Ingram Micro customer number of the tenant.
  - `enabled` (boolean): Search and order through the Ingram Micro API.
  - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Ingram Micro are sent through the Ingram API (off by default).
  - `sandbox` (boolean): Use the sandbox environment.
- `lastEditor` (string, read-only): Who saved the configuration last.
- `lastUpdate` (string (date-time), read-only): When the configuration was last saved.
- `manufacturerMappings` (array of ManufacturerMapping): Manufacturer names and aliases mapped to masterdata manufacturer codes.
  - `aliases` (array of string): Other spellings of the manufacturer in the distributor catalogs.
  - `code` (string): Manufacturer code in masterdata.
  - `id` (string): Id of the mapping.
  - `name` (string): Manufacturer name in masterdata.
- `msp` (TradeMSPConfig)
  - `autoBilling` (object): Window in the month after the billed one in which the drafts are approved without a person, once every active connector collected the month and no subscription lacks a customer or an article: at `from` when nothing blocks, else at every recheck and right after a collection ended, until `to`. When enabled, `from` must lie before `to` and every enabled connector's schedule before `to` (422 otherwise).
    - `enabled` (boolean): Bill the month automatically.
    - `from` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
    - `recheckHours` (integer): Hours until a blocked month (a connector missing, subscriptions without customer or article) is checked again; empty: 4. (max 168)
    - `to` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
  - `enabled` (boolean): MSP billing is on.
  - `ingram` (object): Ingram Micro cloud subscriptions (Microsoft CSP included), read through the Reseller API v7 with the Ingram connection of the distributor settings (`itsp.ingram`). The end customers (details, Custom_Account_ID = our address number) are read from the Cloud Marketplace API with the `marketplace*` access below; optional, without it customers are matched by name only.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Microsoft articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Microsoft articles MSP billing creates for subscriptions without article; without unit and product group none is created.
    - `enabled` (boolean): Collect Ingram Micro marketplace usage.
    - `marketplaceCode` (string): Marketplace code.
    - `marketplaceLogin` (string): Ingram Micro marketplace login.
    - `marketplacePassword` (object): Write-only: stored encrypted, masked in answers; send the mask back to keep it.
    - `marketplaceSubscriptionKey` (object): Subscription key (`X-Subscription-Key`). Write-only: stored encrypted, masked in answers.
    - `marketplaceUrl` (string): Base URL of the Cloud Marketplace API gateway.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `ingram`). Also the supplier of the Microsoft articles MSP billing creates.
  - `itc` (object): ITC Riemer (provider `itc`): no API, its monthly reports are uploaded (`uploadMspItcReport`) and count for the completeness of the month without a schedule.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the ITC articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the ITC articles MSP billing creates for SKUs without article; without unit and product group none is created.
    - `enabled` (boolean): Bill ITC Riemer reports.
    - `supplierAddressId` (string): Masterdata address of ITC Riemer: uploaded reports are filed under it in DMS, it is the supplier of the ITC articles MSP billing creates and the reconciliation compares its inbound invoices.
  - `mailstore` (object): MailStore connection.
    - `enabled` (boolean): Collect MailStore usage.
    - `password` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `schedule` (object): When the previous month is collected each month.
    - `supplierAddressId` (string): Masterdata address of the supplier whose inbound invoices the reconciliation compares; empty: the address linked with the distributor id `mailstore`.
    - `url` (string): URL of the MailStore SPE.
    - `username` (string): MailStore user name.
  - `notify` (object): Who is told about the connector runs and the automatic billing.
    - `recipients` (array of string (email)): E-mail addresses; trimmed, empty and repeated ones dropped.
  - `sophos` (object): Sophos connection.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Sophos articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Sophos articles MSP billing creates from the Infinigate catalog for SKUs without article; without unit and product group none is created.
    - `clientId` (string): Sophos API client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `enabled` (boolean): Collect Sophos usage.
    - `partnerId` (string): Sophos partner id.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `sophos`). Also the supplier of the Sophos articles MSP billing creates (else the address of the distributor id `infinigate`).
  - `taxRate` (number): VAT rate of the MSP invoices in percent; empty: 19. (max 100)

Example:

```json
{
  "active": true,
  "aiEnrichment": {
    "enabled": true,
    "model": ""
  },
  "amazon": {
    "baseUrl": "",
    "clientId": "",
    "clientSecret": "",
    "enabled": false,
    "locale": "de_DE",
    "refreshToken": "",
    "region": "EU",
    "sandbox": false,
    "userEmail": ""
  },
  "egis": {
    "baseUrl": "",
    "enabled": true,
    "erp": "ConnectCloud",
    "login": "EXAMPLE-egis-login",
    "password": "••••••••"
  },
  "infinigate": {
    "apiKey": "••••••••",
    "baseUrl": "",
    "clientId": "EXAMPLE-infinigate-client-id",
    "clientSecret": "••••••••",
    "enabled": true,
    "orderingEnabled": false,
    "testMode": false
  },
  "ingram": {
    "baseUrl": "",
    "clientId": "EXAMPLE-ingram-client-id",
    "clientSecret": "••••••••",
    "countryCode": "DE",
    "customerNumber": "EXAMPLE-20-123456",
    "enabled": true,
    "orderingEnabled": true,
    "sandbox": false
  },
  "lastEditor": "laura.kaestner@muster-it.example",
  "lastUpdate": "2026-11-18T15:40:00Z",
  "manufacturerMappings": [
    {
      "aliases": [
        "HP Enterprise",
        "HPE Aruba"
      ],
      "code": "HPE",
      "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b01",
      "name": "Hewlett Packard Enterprise"
    },
    {
      "aliases": [
        "Lenovo Global Technology",
        "LENOVO DCG"
      ],
      "code": "LNV",
      "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b02",
      "name": "Lenovo"
    }
  ],
  "msp": {
    "autoBilling": {
      "enabled": true,
      "from": {
        "day": 5,
        "time": "06:00"
      },
      "recheckHours": 4,
      "to": {
        "day": 10,
        "time": "17:00"
      }
    },
    "enabled": true,
    "ingram": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "enabled": true,
      "marketplaceCode": "de",
      "marketplaceLogin": "EXAMPLE-marketplace-login",
      "marketplacePassword": "••••••••",
      "marketplaceSubscriptionKey": "••••••••",
      "marketplaceUrl": "https://marketplace.ingram.example",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"
    },
    "itc": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05",
      "articleUnitCode": "MON",
      "enabled": true,
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"
    },
    "mailstore": {
      "enabled": true,
      "password": "••••••••",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "",
      "url": "https://mailstore.muster-it.example:8474",
      "username": "EXAMPLE-api-user"
    },
    "notify": {
      "recipients": [
        "laura.kaestner@muster-it.example",
        "christina.adler@muster-it.example"
      ]
    },
    "sophos": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "clientId": "EXAMPLE-sophos-client-id",
      "clientSecret": "••••••••",
      "enabled": true,
      "partnerId": "EXAMPLE-sophos-partner-id",
      "schedule": {
        "day": 2,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"
    },
    "taxRate": 19
  }
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **422** The `msp` section is invalid: schedule day or time, automatic billing window (`from` must lie before `to`), tax rate, notification addresses. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `active` (boolean, read-only): True while any connection on the page is enabled.
- `aiEnrichment` (AIEnrichmentConfig): Null until saved once.
  - `enabled` (boolean): Propose article texts and product groups with AI.
  - `model` (string): AI model of the enrichment; empty uses the default.
- `amazon` (AmazonConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `enabled` (boolean): Search the Amazon Business catalog.
  - `locale` (string): Locale of the product data (e.g. `de_DE`).
  - `refreshToken` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `region` (string): Amazon region of the account.
  - `sandbox` (boolean): Use the sandbox environment.
  - `userEmail` (string): E-mail of the Amazon Business user the searches run as.
- `egis` (EgisConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `enabled` (boolean): Search and order through EGIS.
  - `erp` (string): ERP name sent to EGIS; empty uses the default.
  - `login` (string): EGIS login. (max length 40)
  - `password` (object): EGIS password; masked in answers, the mask or an empty value keeps the stored one. (max length 40)
- `infinigate` (InfinigateConfig)
  - `apiKey` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `enabled` (boolean): Search and order through the Infinigate API.
  - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Infinigate are sent through the Infinigate API (off by default; not available yet).
  - `testMode` (boolean): Use the Infinigate test environment.
- `ingram` (IngramCatalogConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `countryCode` (string): Ingram Micro country of the account (ISO 3166-1 alpha-2).
  - `customerNumber` (string): Ingram Micro customer number of the tenant.
  - `enabled` (boolean): Search and order through the Ingram Micro API.
  - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Ingram Micro are sent through the Ingram API (off by default).
  - `sandbox` (boolean): Use the sandbox environment.
- `lastEditor` (string, read-only): Who saved the configuration last.
- `lastUpdate` (string (date-time), read-only): When the configuration was last saved.
- `manufacturerMappings` (array of ManufacturerMapping): Manufacturer names and aliases mapped to masterdata manufacturer codes.
  - `aliases` (array of string): Other spellings of the manufacturer in the distributor catalogs.
  - `code` (string): Manufacturer code in masterdata.
  - `id` (string): Id of the mapping.
  - `name` (string): Manufacturer name in masterdata.
- `msp` (TradeMSPConfig)
  - `autoBilling` (object): Window in the month after the billed one in which the drafts are approved without a person, once every active connector collected the month and no subscription lacks a customer or an article: at `from` when nothing blocks, else at every recheck and right after a collection ended, until `to`. When enabled, `from` must lie before `to` and every enabled connector's schedule before `to` (422 otherwise).
    - `enabled` (boolean): Bill the month automatically.
    - `from` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
    - `recheckHours` (integer): Hours until a blocked month (a connector missing, subscriptions without customer or article) is checked again; empty: 4. (max 168)
    - `to` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
  - `enabled` (boolean): MSP billing is on.
  - `ingram` (object): Ingram Micro cloud subscriptions (Microsoft CSP included), read through the Reseller API v7 with the Ingram connection of the distributor settings (`itsp.ingram`). The end customers (details, Custom_Account_ID = our address number) are read from the Cloud Marketplace API with the `marketplace*` access below; optional, without it customers are matched by name only.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Microsoft articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Microsoft articles MSP billing creates for subscriptions without article; without unit and product group none is created.
    - `enabled` (boolean): Collect Ingram Micro marketplace usage.
    - `marketplaceCode` (string): Marketplace code.
    - `marketplaceLogin` (string): Ingram Micro marketplace login.
    - `marketplacePassword` (object): Write-only: stored encrypted, masked in answers; send the mask back to keep it.
    - `marketplaceSubscriptionKey` (object): Subscription key (`X-Subscription-Key`). Write-only: stored encrypted, masked in answers.
    - `marketplaceUrl` (string): Base URL of the Cloud Marketplace API gateway.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `ingram`). Also the supplier of the Microsoft articles MSP billing creates.
  - `itc` (object): ITC Riemer (provider `itc`): no API, its monthly reports are uploaded (`uploadMspItcReport`) and count for the completeness of the month without a schedule.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the ITC articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the ITC articles MSP billing creates for SKUs without article; without unit and product group none is created.
    - `enabled` (boolean): Bill ITC Riemer reports.
    - `supplierAddressId` (string): Masterdata address of ITC Riemer: uploaded reports are filed under it in DMS, it is the supplier of the ITC articles MSP billing creates and the reconciliation compares its inbound invoices.
  - `mailstore` (object): MailStore connection.
    - `enabled` (boolean): Collect MailStore usage.
    - `password` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `schedule` (object): When the previous month is collected each month.
    - `supplierAddressId` (string): Masterdata address of the supplier whose inbound invoices the reconciliation compares; empty: the address linked with the distributor id `mailstore`.
    - `url` (string): URL of the MailStore SPE.
    - `username` (string): MailStore user name.
  - `notify` (object): Who is told about the connector runs and the automatic billing.
    - `recipients` (array of string (email)): E-mail addresses; trimmed, empty and repeated ones dropped.
  - `sophos` (object): Sophos connection.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Sophos articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Sophos articles MSP billing creates from the Infinigate catalog for SKUs without article; without unit and product group none is created.
    - `clientId` (string): Sophos API client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `enabled` (boolean): Collect Sophos usage.
    - `partnerId` (string): Sophos partner id.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `sophos`). Also the supplier of the Sophos articles MSP billing creates (else the address of the distributor id `infinigate`).
  - `taxRate` (number): VAT rate of the MSP invoices in percent; empty: 19. (max 100)

Example 200 answer:

```json
{
  "active": true,
  "aiEnrichment": {
    "enabled": true,
    "model": ""
  },
  "amazon": {
    "baseUrl": "",
    "clientId": "",
    "clientSecret": "",
    "enabled": false,
    "locale": "de_DE",
    "refreshToken": "",
    "region": "EU",
    "sandbox": false,
    "userEmail": ""
  },
  "egis": {
    "baseUrl": "",
    "enabled": true,
    "erp": "ConnectCloud",
    "login": "EXAMPLE-egis-login",
    "password": "••••••••"
  },
  "infinigate": {
    "apiKey": "••••••••",
    "baseUrl": "",
    "clientId": "EXAMPLE-infinigate-client-id",
    "clientSecret": "••••••••",
    "enabled": true,
    "orderingEnabled": false,
    "testMode": false
  },
  "ingram": {
    "baseUrl": "",
    "clientId": "EXAMPLE-ingram-client-id",
    "clientSecret": "••••••••",
    "countryCode": "DE",
    "customerNumber": "EXAMPLE-20-123456",
    "enabled": true,
    "orderingEnabled": true,
    "sandbox": false
  },
  "lastEditor": "laura.kaestner@muster-it.example",
  "lastUpdate": "2026-11-18T15:40:00Z",
  "manufacturerMappings": [
    {
      "aliases": [
        "HP Enterprise",
        "HPE Aruba"
      ],
      "code": "HPE",
      "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b01",
      "name": "Hewlett Packard Enterprise"
    },
    {
      "aliases": [
        "Lenovo Global Technology",
        "LENOVO DCG"
      ],
      "code": "LNV",
      "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b02",
      "name": "Lenovo"
    }
  ],
  "msp": {
    "autoBilling": {
      "enabled": true,
      "from": {
        "day": 5,
        "time": "06:00"
      },
      "recheckHours": 4,
      "to": {
        "day": 10,
        "time": "17:00"
      }
    },
    "enabled": true,
    "ingram": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "enabled": true,
      "marketplaceCode": "de",
      "marketplaceLogin": "EXAMPLE-marketplace-login",
      "marketplacePassword": "••••••••",
      "marketplaceSubscriptionKey": "••••••••",
      "marketplaceUrl": "https://marketplace.ingram.example",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"
    },
    "itc": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05",
      "articleUnitCode": "MON",
      "enabled": true,
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"
    },
    "mailstore": {
      "enabled": true,
      "password": "••••••••",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "",
      "url": "https://mailstore.muster-it.example:8474",
      "username": "EXAMPLE-api-user"
    },
    "notify": {
      "recipients": [
        "laura.kaestner@muster-it.example",
        "christina.adler@muster-it.example"
      ]
    },
    "sophos": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "clientId": "EXAMPLE-sophos-client-id",
      "clientSecret": "••••••••",
      "enabled": true,
      "partnerId": "EXAMPLE-sophos-partner-id",
      "schedule": {
        "day": 2,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"
    },
    "taxRate": 19
  }
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/itsp/config' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true,"aiEnrichment":{"enabled":true,"model":""},"amazon":{"baseUrl":"","clientId":"","clientSecret":"","enabled":false,"locale":"de_DE","refreshToken":"","region":"EU","sandbox":false,"userEmail":""},"egis":{"baseUrl":"","enabled":true,"erp":"ConnectCloud","login":"EXAMPLE-egis-login","password":"••••••••"},"infinigate":{"apiKey":"••••••••","baseUrl":"","clientId":"EXAMPLE-infinigate-client-id","clientSecret":"••••••••","enabled":true,"orderingEnabled":false,"testMode":false},"ingram":{"baseUrl":"","clientId":"EXAMPLE-ingram-client-id","clientSecret":"••••••••","countryCode":"DE","customerNumber":"EXAMPLE-20-123456","enabled":true,"orderingEnabled":true,"sandbox":false},"lastEditor":"laura.kaestner@muster-it.example","lastUpdate":"2026-11-18T15:40:00Z","manufacturerMappings":[{"aliases":["HP Enterprise","HPE Aruba"],"code":"HPE","id":"7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b01","name":"Hewlett Packard Enterprise"},{"aliases":["Lenovo Global Technology","LENOVO DCG"],"code":"LNV","id":"7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b02","name":"Lenovo"}],"msp":{"autoBilling":{"enabled":true,"from":{"day":5,"time":"06:00"},"recheckHours":4,"to":{"day":10,"time":"17:00"}},"enabled":true,"ingram":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04","articleUnitCode":"LIZ","enabled":true,"marketplaceCode":"de","marketplaceLogin":"EXAMPLE-marketplace-login","marketplacePassword":"••••••••","marketplaceSubscriptionKey":"••••••••","marketplaceUrl":"https://marketplace.ingram.example","schedule":{"day":1,"time":"06:00"},"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"},"itc":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05","articleUnitCode":"MON","enabled":true,"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"},"mailstore":{"enabled":true,"password":"••••••••","schedule":{"day":1,"time":"06:00"},"supplierAddressId":"","url":"https://mailstore.muster-it.example:8474","username":"EXAMPLE-api-user"},"notify":{"recipients":["laura.kaestner@muster-it.example","christina.adler@muster-it.example"]},"sophos":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04","articleUnitCode":"LIZ","clientId":"EXAMPLE-sophos-client-id","clientSecret":"••••••••","enabled":true,"partnerId":"EXAMPLE-sophos-partner-id","schedule":{"day":2,"time":"06:00"},"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"},"taxRate":19}}'
```

## EGIS suppliers with suggested supplier addresses (tenant:settings:read)

`GET /api/trade/v1/itsp/config/egis/suppliers`

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

### Responses

- **200** Suppliers and addresses (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `microtechAddresses` (array of VendorAddressSummary): Supplier addresses of masterdata to choose from.
  - `addressNo` (integer): Address number in masterdata.
  - `city` (string): City.
  - `country` (string): Country.
  - `id` (string): Masterdata address id.
  - `name1` (string): Name (line 1).
  - `name2` (string): Name (line 2).
  - `street` (string): Street and house number.
  - `taxId` (string): Tax number.
  - `vatId` (string): VAT identification number.
  - `zipCode` (string): Postal code.
- `suppliers` (array of object): EGIS distributors with the supplier address suggested for each.
  - `city` (string): City.
  - `confidence` (string): Confidence of the suggestion: `HIGH`, `MEDIUM`, `LOW` or `NONE`. (one of `HIGH`, `MEDIUM`, `LOW`, `NONE`)
  - `country` (string): Country.
  - `currentAddressNo` (integer): Address number of the supplier address mapped now.
  - `distributorId` (string): EGIS id of the distributor.
  - `distributorName` (string): Name of the distributor.
  - `isMapped` (boolean): The distributor is mapped to a supplier address already.
  - `matchReason` (string): Why the address was suggested.
  - `name1` (string): Name (line 1) of the distributor at EGIS.
  - `name2` (string): Name (line 2) of the distributor at EGIS.
  - `street` (string): Street and house number.
  - `suggestedAddressName` (string): Name of the suggested masterdata supplier address.
  - `suggestedAddressNo` (integer): Address number of the suggested masterdata supplier address.
  - `taxId` (string): Tax number.
  - `vatId` (string): VAT identification number.
  - `zipCode` (string): Postal code.

Example 200 answer:

```json
{
  "microtechAddresses": [
    {
      "addressNo": 70001,
      "city": "Hamburg",
      "country": "DE",
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "name1": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zipCode": "20457"
    },
    {
      "addressNo": 70002,
      "city": "Augsburg",
      "country": "DE",
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
      "name1": "Kabelwerk Süd GmbH",
      "street": "Gewerbering 7",
      "vatId": "DE701000002",
      "zipCode": "86167"
    }
  ],
  "suppliers": [
    {
      "city": "Hamburg",
      "confidence": "HIGH",
      "country": "DE",
      "currentAddressNo": 70001,
      "distributorId": "70044",
      "distributorName": "Nordlicht IT-Distribution GmbH",
      "isMapped": true,
      "matchReason": "USt-IdNr. stimmt überein",
      "name1": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "suggestedAddressName": "Nordlicht IT-Distribution GmbH",
      "suggestedAddressNo": 70001,
      "vatId": "DE701000001",
      "zipCode": "20457"
    },
    {
      "city": "Augsburg",
      "confidence": "HIGH",
      "country": "DE",
      "distributorId": "70282",
      "distributorName": "Kabelwerk Süd GmbH",
      "isMapped": false,
      "matchReason": "USt-IdNr. stimmt überein",
      "name1": "Kabelwerk Süd GmbH",
      "street": "Gewerbering 7",
      "suggestedAddressName": "Kabelwerk Süd GmbH",
      "suggestedAddressNo": 70002,
      "vatId": "DE701000002",
      "zipCode": "86167"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/itsp/config/egis/suppliers' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Supplier addresses of masterdata (tenant:settings:read)

`GET /api/trade/v1/itsp/config/vendor-addresses`

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

### Responses

- **200** Addresses (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `items` (array of VendorAddressSummary, required)
  - `addressNo` (integer): Address number in masterdata.
  - `city` (string): City.
  - `country` (string): Country.
  - `id` (string): Masterdata address id.
  - `name1` (string): Name (line 1).
  - `name2` (string): Name (line 2).
  - `street` (string): Street and house number.
  - `taxId` (string): Tax number.
  - `vatId` (string): VAT identification number.
  - `zipCode` (string): Postal code.

Example 200 answer:

```json
{
  "items": [
    {
      "addressNo": 70001,
      "city": "Hamburg",
      "country": "DE",
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "name1": "Nordlicht IT-Distribution GmbH",
      "street": "Hafenstraße 40",
      "vatId": "DE701000001",
      "zipCode": "20457"
    },
    {
      "addressNo": 70002,
      "city": "Augsburg",
      "country": "DE",
      "id": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
      "name1": "Kabelwerk Süd GmbH",
      "street": "Gewerbering 7",
      "vatId": "DE701000002",
      "zipCode": "86167"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/itsp/config/vendor-addresses' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Test the credentials of one connector without saving (tenant:settings:write)

`POST /api/trade/v1/itsp/config/test/{connector}`

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

The body is the configuration as entered (same shape as `saveItspConfig`); masked secrets are taken from the stored configuration. A failed check is a `200` with `ok: false` and a German `message`; the check gives up after 25 seconds.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `connector` | path | string | yes | (one of `egis`, `ingram`, `infinigate`, `amazon`, `mailstore`, `sophos`, `msp-ingram`) |

### Request body

`application/json` (required)

- `active` (boolean, read-only): True while any connection on the page is enabled.
- `aiEnrichment` (AIEnrichmentConfig): Null until saved once.
  - `enabled` (boolean): Propose article texts and product groups with AI.
  - `model` (string): AI model of the enrichment; empty uses the default.
- `amazon` (AmazonConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `enabled` (boolean): Search the Amazon Business catalog.
  - `locale` (string): Locale of the product data (e.g. `de_DE`).
  - `refreshToken` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `region` (string): Amazon region of the account.
  - `sandbox` (boolean): Use the sandbox environment.
  - `userEmail` (string): E-mail of the Amazon Business user the searches run as.
- `egis` (EgisConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `enabled` (boolean): Search and order through EGIS.
  - `erp` (string): ERP name sent to EGIS; empty uses the default.
  - `login` (string): EGIS login. (max length 40)
  - `password` (object): EGIS password; masked in answers, the mask or an empty value keeps the stored one. (max length 40)
- `infinigate` (InfinigateConfig)
  - `apiKey` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `enabled` (boolean): Search and order through the Infinigate API.
  - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Infinigate are sent through the Infinigate API (off by default; not available yet).
  - `testMode` (boolean): Use the Infinigate test environment.
- `ingram` (IngramCatalogConfig)
  - `baseUrl` (string): Base URL of the API; empty uses the default.
  - `clientId` (string): OAuth client id.
  - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
  - `countryCode` (string): Ingram Micro country of the account (ISO 3166-1 alpha-2).
  - `customerNumber` (string): Ingram Micro customer number of the tenant.
  - `enabled` (boolean): Search and order through the Ingram Micro API.
  - `orderingEnabled` (boolean): Purchase orders of suppliers linked to Ingram Micro are sent through the Ingram API (off by default).
  - `sandbox` (boolean): Use the sandbox environment.
- `lastEditor` (string, read-only): Who saved the configuration last.
- `lastUpdate` (string (date-time), read-only): When the configuration was last saved.
- `manufacturerMappings` (array of ManufacturerMapping): Manufacturer names and aliases mapped to masterdata manufacturer codes.
  - `aliases` (array of string): Other spellings of the manufacturer in the distributor catalogs.
  - `code` (string): Manufacturer code in masterdata.
  - `id` (string): Id of the mapping.
  - `name` (string): Manufacturer name in masterdata.
- `msp` (TradeMSPConfig)
  - `autoBilling` (object): Window in the month after the billed one in which the drafts are approved without a person, once every active connector collected the month and no subscription lacks a customer or an article: at `from` when nothing blocks, else at every recheck and right after a collection ended, until `to`. When enabled, `from` must lie before `to` and every enabled connector's schedule before `to` (422 otherwise).
    - `enabled` (boolean): Bill the month automatically.
    - `from` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
    - `recheckHours` (integer): Hours until a blocked month (a connector missing, subscriptions without customer or article) is checked again; empty: 4. (max 168)
    - `to` (MspSchedule): A day of the month and a time of day (Europe/Berlin); unset values take the defaults (day 1, 06:00).
      - `day` (integer): Day of the month (1–28). (max 28)
      - `time` (string): `HH:MM`, 24 h.
  - `enabled` (boolean): MSP billing is on.
  - `ingram` (object): Ingram Micro cloud subscriptions (Microsoft CSP included), read through the Reseller API v7 with the Ingram connection of the distributor settings (`itsp.ingram`). The end customers (details, Custom_Account_ID = our address number) are read from the Cloud Marketplace API with the `marketplace*` access below; optional, without it customers are matched by name only.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Microsoft articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Microsoft articles MSP billing creates for subscriptions without article; without unit and product group none is created.
    - `enabled` (boolean): Collect Ingram Micro marketplace usage.
    - `marketplaceCode` (string): Marketplace code.
    - `marketplaceLogin` (string): Ingram Micro marketplace login.
    - `marketplacePassword` (object): Write-only: stored encrypted, masked in answers; send the mask back to keep it.
    - `marketplaceSubscriptionKey` (object): Subscription key (`X-Subscription-Key`). Write-only: stored encrypted, masked in answers.
    - `marketplaceUrl` (string): Base URL of the Cloud Marketplace API gateway.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `ingram`). Also the supplier of the Microsoft articles MSP billing creates.
  - `itc` (object): ITC Riemer (provider `itc`): no API, its monthly reports are uploaded (`uploadMspItcReport`) and count for the completeness of the month without a schedule.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the ITC articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the ITC articles MSP billing creates for SKUs without article; without unit and product group none is created.
    - `enabled` (boolean): Bill ITC Riemer reports.
    - `supplierAddressId` (string): Masterdata address of ITC Riemer: uploaded reports are filed under it in DMS, it is the supplier of the ITC articles MSP billing creates and the reconciliation compares its inbound invoices.
  - `mailstore` (object): MailStore connection.
    - `enabled` (boolean): Collect MailStore usage.
    - `password` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `schedule` (object): When the previous month is collected each month.
    - `supplierAddressId` (string): Masterdata address of the supplier whose inbound invoices the reconciliation compares; empty: the address linked with the distributor id `mailstore`.
    - `url` (string): URL of the MailStore SPE.
    - `username` (string): MailStore user name.
  - `notify` (object): Who is told about the connector runs and the automatic billing.
    - `recipients` (array of string (email)): E-mail addresses; trimmed, empty and repeated ones dropped.
  - `sophos` (object): Sophos connection.
    - `articleProductGroupId` (string (uuid)): Masterdata product group of the Sophos articles MSP billing creates (see `articleUnitCode`).
    - `articleUnitCode` (string): Masterdata unit code of the Sophos articles MSP billing creates from the Infinigate catalog for SKUs without article; without unit and product group none is created.
    - `clientId` (string): Sophos API client id.
    - `clientSecret` (Secret): Masked (`••••••••`) in answers; send the mask or an empty value to keep the stored secret.
    - `enabled` (boolean): Collect Sophos usage.
    - `partnerId` (string): Sophos partner id.
    - `schedule` (object): See `mailstore`.
    - `supplierAddressId` (string): See `mailstore` (distributor id `sophos`). Also the supplier of the Sophos articles MSP billing creates (else the address of the distributor id `infinigate`).
  - `taxRate` (number): VAT rate of the MSP invoices in percent; empty: 19. (max 100)

Example:

```json
{
  "active": true,
  "aiEnrichment": {
    "enabled": true,
    "model": ""
  },
  "amazon": {
    "baseUrl": "",
    "clientId": "",
    "clientSecret": "",
    "enabled": false,
    "locale": "de_DE",
    "refreshToken": "",
    "region": "EU",
    "sandbox": false,
    "userEmail": ""
  },
  "egis": {
    "baseUrl": "",
    "enabled": true,
    "erp": "ConnectCloud",
    "login": "EXAMPLE-egis-login",
    "password": "••••••••"
  },
  "infinigate": {
    "apiKey": "••••••••",
    "baseUrl": "",
    "clientId": "EXAMPLE-infinigate-client-id",
    "clientSecret": "••••••••",
    "enabled": true,
    "orderingEnabled": false,
    "testMode": false
  },
  "ingram": {
    "baseUrl": "",
    "clientId": "EXAMPLE-ingram-client-id",
    "clientSecret": "••••••••",
    "countryCode": "DE",
    "customerNumber": "EXAMPLE-20-123456",
    "enabled": true,
    "orderingEnabled": true,
    "sandbox": false
  },
  "lastEditor": "laura.kaestner@muster-it.example",
  "lastUpdate": "2026-11-18T15:40:00Z",
  "manufacturerMappings": [
    {
      "aliases": [
        "HP Enterprise",
        "HPE Aruba"
      ],
      "code": "HPE",
      "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b01",
      "name": "Hewlett Packard Enterprise"
    },
    {
      "aliases": [
        "Lenovo Global Technology",
        "LENOVO DCG"
      ],
      "code": "LNV",
      "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b02",
      "name": "Lenovo"
    }
  ],
  "msp": {
    "autoBilling": {
      "enabled": true,
      "from": {
        "day": 5,
        "time": "06:00"
      },
      "recheckHours": 4,
      "to": {
        "day": 10,
        "time": "17:00"
      }
    },
    "enabled": true,
    "ingram": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "enabled": true,
      "marketplaceCode": "de",
      "marketplaceLogin": "EXAMPLE-marketplace-login",
      "marketplacePassword": "••••••••",
      "marketplaceSubscriptionKey": "••••••••",
      "marketplaceUrl": "https://marketplace.ingram.example",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"
    },
    "itc": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05",
      "articleUnitCode": "MON",
      "enabled": true,
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"
    },
    "mailstore": {
      "enabled": true,
      "password": "••••••••",
      "schedule": {
        "day": 1,
        "time": "06:00"
      },
      "supplierAddressId": "",
      "url": "https://mailstore.muster-it.example:8474",
      "username": "EXAMPLE-api-user"
    },
    "notify": {
      "recipients": [
        "laura.kaestner@muster-it.example",
        "christina.adler@muster-it.example"
      ]
    },
    "sophos": {
      "articleProductGroupId": "9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04",
      "articleUnitCode": "LIZ",
      "clientId": "EXAMPLE-sophos-client-id",
      "clientSecret": "••••••••",
      "enabled": true,
      "partnerId": "EXAMPLE-sophos-partner-id",
      "schedule": {
        "day": 2,
        "time": "06:00"
      },
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"
    },
    "taxRate": 19
  }
}
```

### Responses

- **200** Result (`application/json`)
- **400** Invalid body or unknown connector. (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `connector` (string): The connector tested.
- `durationMs` (integer): Duration of the test in milliseconds.
- `environment` (string): `Produktiv`, `Sandbox` or `Test`, where the connector has one. (one of `Produktiv`, `Sandbox`, `Test`)
- `message` (string): German result text.
- `ok` (boolean): The credentials work.

Example 200 answer:

```json
{
  "connector": "egis",
  "durationMs": 842,
  "environment": "Produktiv",
  "message": "Anmeldung erfolgreich – 12 Lieferanten für Ihren Zugang freigeschaltet.",
  "ok": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/itsp/config/test/egis' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true,"aiEnrichment":{"enabled":true,"model":""},"amazon":{"baseUrl":"","clientId":"","clientSecret":"","enabled":false,"locale":"de_DE","refreshToken":"","region":"EU","sandbox":false,"userEmail":""},"egis":{"baseUrl":"","enabled":true,"erp":"ConnectCloud","login":"EXAMPLE-egis-login","password":"••••••••"},"infinigate":{"apiKey":"••••••••","baseUrl":"","clientId":"EXAMPLE-infinigate-client-id","clientSecret":"••••••••","enabled":true,"orderingEnabled":false,"testMode":false},"ingram":{"baseUrl":"","clientId":"EXAMPLE-ingram-client-id","clientSecret":"••••••••","countryCode":"DE","customerNumber":"EXAMPLE-20-123456","enabled":true,"orderingEnabled":true,"sandbox":false},"lastEditor":"laura.kaestner@muster-it.example","lastUpdate":"2026-11-18T15:40:00Z","manufacturerMappings":[{"aliases":["HP Enterprise","HPE Aruba"],"code":"HPE","id":"7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b01","name":"Hewlett Packard Enterprise"},{"aliases":["Lenovo Global Technology","LENOVO DCG"],"code":"LNV","id":"7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b02","name":"Lenovo"}],"msp":{"autoBilling":{"enabled":true,"from":{"day":5,"time":"06:00"},"recheckHours":4,"to":{"day":10,"time":"17:00"}},"enabled":true,"ingram":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04","articleUnitCode":"LIZ","enabled":true,"marketplaceCode":"de","marketplaceLogin":"EXAMPLE-marketplace-login","marketplacePassword":"••••••••","marketplaceSubscriptionKey":"••••••••","marketplaceUrl":"https://marketplace.ingram.example","schedule":{"day":1,"time":"06:00"},"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10"},"itc":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c05","articleUnitCode":"MON","enabled":true,"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03"},"mailstore":{"enabled":true,"password":"••••••••","schedule":{"day":1,"time":"06:00"},"supplierAddressId":"","url":"https://mailstore.muster-it.example:8474","username":"EXAMPLE-api-user"},"notify":{"recipients":["laura.kaestner@muster-it.example","christina.adler@muster-it.example"]},"sophos":{"articleProductGroupId":"9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c04","articleUnitCode":"LIZ","clientId":"EXAMPLE-sophos-client-id","clientSecret":"••••••••","enabled":true,"partnerId":"EXAMPLE-sophos-partner-id","schedule":{"day":2,"time":"06:00"},"supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d11"},"taxRate":19}}'
```

# ITSP

## Search the distributor catalogs (tenant:trade:purchasing:read)

`POST /api/trade/v1/itsp/articles/search`

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

Searches the enabled distributors of the tenant (EGIS, Ingram Micro, Infinigate, Amazon) and
aggregates the offers per product. Articles that already exist in masterdata are marked
(`microtechStatus`); supplier addresses are filled in from masterdata. Connector failures are
reported in `warnings`.

### Request body

`application/json` (required)

- `query` (string, required)
- `enrichWithAi` (boolean): Accepted but not used by the search.
- `options` (SearchOptions)
  - `connectors` (array of string): Limit the search to these connectors (e.g. `egis`, `ingram`, `infinigate`, `amazon`).
  - `maxResults` (integer): Maximum number of articles.
  - `onlyInStock` (boolean): Only articles a distributor has in stock.

Example:

```json
{
  "options": {
    "connectors": [
      "egis",
      "ingram",
      "amazon"
    ],
    "maxResults": 20,
    "onlyInStock": true
  },
  "query": "Lenovo ThinkPad T14"
}
```

### Responses

- **200** Results (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `articles` (array of NormalizedArticle): Articles found, merged across distributors.
  - `bestPurchasePrice` (number): Lowest purchase price of all supplier offers.
  - `canonicalMpn` (string): Manufacturer part number normalized for matching.
  - `currency` (string): Currency (ISO 4217).
  - `description` (string): Description of the article.
  - `descriptions` (array of object): Every text the catalogs have for the article.
    - `recommended` (boolean): The catalog flags the text as recommended.
    - `source` (string): Catalog of the text, e.g. `CNET`, `ICECAT`, `EGIS`.
    - `text` (string): The text.
    - `title` (string): Title of the text, e.g. `Marketing-Text (CNET)`.
    - `type` (string): `main`, `marketing`, `short_summary`, `long_summary` or `short_desc`. (one of `main`, `marketing`, `short_summary`, `long_summary`, `short_desc`)
  - `ean` (string): EAN (GTIN) of the article.
  - `existingArticleId` (string): Masterdata id of the existing article.
  - `existingArticleNumber` (string): Article number of the article that exists in masterdata already.
  - `features` (array of object): Technical features of the article.
    - `name` (string): Name of the feature.
    - `value` (string): Value of the feature.
  - `fldSerienNrKz` (boolean): Serial number tracked.
  - `height` (number): Height of the article.
  - `id` (string): Id of the article in the merged search result.
  - `imageUrl` (string): Link to a product image.
  - `inStock` (boolean): Stock confirmed without a quantity.
  - `length` (number): Length of the article.
  - `manufacturerCode` (string): Manufacturer code in masterdata.
  - `manufacturerId` (string): The catalog's id of the manufacturer.
  - `manufacturerName` (string): Name of the manufacturer.
  - `marketingText` (string): Marketing text of the article.
  - `microtechArticleNumber` (string): Article number of the article in the ERP, when it exists there.
  - `microtechStatus` (string): Whether the article exists in masterdata. (one of `NOT_FOUND`, `EXISTS`, `MULTIPLE_MATCHES`, `REQUIRES_MANUAL_MAPPING`)
  - `mpn` (string): Manufacturer part number.
  - `productGroup` (string): Name of the product group.
  - `productGroupNumber` (string): Number of the product group in masterdata.
  - `requiresManualMapping` (boolean): The manufacturer could not be mapped to masterdata automatically.
  - `searchTerm` (string): Search term (Suchbegriff) of the article.
  - `shortDescription` (string): Short description of the article.
  - `source` (string): Catalog the article came from; comma-separated when several had it.
  - `sourceArticleId` (string): The catalog's id of the article.
  - `sourceIdentifiers` (object): Connector → its article id.
  - `suppliers` (array of SupplierArticle): Supplier offers of the article.
    - `availableQuantity` (number): Quantity available at the distributor.
    - `currency` (string): Currency of the purchase price (ISO 4217).
    - `deliveryTimeDays` (integer): Delivery time in days.
    - `directOrderable` (boolean): The article can be ordered from the distributor through trade.
    - `distributorId` (string): EGIS id of the distributor.
    - `distributorName` (string): Name of the distributor.
    - `isDefault` (boolean): This supplier is the default supplier of the article.
    - `microtechAddressNo` (integer): Address number of the supplier in masterdata.
    - `purchasePrice` (number): Net purchase price.
    - `source` (string): Catalog of the offer (`egis`, `ingram`, …).
    - `supplierAddressId` (string): Masterdata address the distributor is assigned to.
    - `supplierAddressName` (string): Name of the masterdata supplier address of the distributor.
    - `supplierArticleNumber` (string): The distributor's article number.
  - `title` (string): Title of the article.
  - `totalAvailableQuantity` (number): Quantity available across all distributors.
  - `unit` (string): Unit of measure.
  - `weight` (number): Weight of the article.
  - `width` (number): Width of the article.
- `total` (integer): Number of articles found.
- `warnings` (array of ConnectorWarning): Connectors that failed or answered partly.
  - `code` (string): Machine-readable kind of the warning; empty for other failures (the message names them). Known values: `PRICES_UNAVAILABLE` (the connector could not answer prices and availability; its offers are missing, article data it read is still returned).
  - `connector` (string): The connector that did not answer fully.
  - `message` (string): What went wrong.

Example 200 answer:

```json
{
  "articles": [
    {
      "bestPurchasePrice": 1049,
      "canonicalMpn": "21MC0012GE",
      "currency": "EUR",
      "descriptions": [
        {
          "recommended": true,
          "source": "EGIS",
          "text": "Business-Notebook mit 14-Zoll-WUXGA-Display, Intel Core Ultra 7 155U, 32 GB RAM und 1 TB SSD.",
          "title": "Produktbeschreibung (EGIS)",
          "type": "main"
        }
      ],
      "ean": "0197529876543",
      "features": [
        {
          "name": "Bildschirmdiagonale",
          "value": "35,6 cm (14\")"
        },
        {
          "name": "Prozessor",
          "value": "Intel Core Ultra 7 155U"
        }
      ],
      "fldSerienNrKz": true,
      "id": "art-21MC0012GE",
      "inStock": true,
      "manufacturerCode": "LNV",
      "manufacturerName": "Lenovo",
      "microtechStatus": "NOT_FOUND",
      "mpn": "21MC0012GE",
      "productGroup": "Notebooks",
      "productGroupNumber": "120",
      "requiresManualMapping": false,
      "searchTerm": "THINKPAD T14 G5",
      "shortDescription": "Lenovo ThinkPad T14 Gen 5",
      "source": "egis,ingram",
      "sourceArticleId": "PCS512377",
      "sourceIdentifiers": {
        "egis": "PCS512377",
        "ingram": "7J0815"
      },
      "suppliers": [
        {
          "availableQuantity": 25,
          "currency": "EUR",
          "deliveryTimeDays": 1,
          "directOrderable": true,
          "distributorId": "70044",
          "distributorName": "Nordlicht IT-Distribution GmbH",
          "isDefault": true,
          "microtechAddressNo": 70001,
          "purchasePrice": 1049,
          "source": "egis",
          "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
          "supplierAddressName": "Nordlicht IT-Distribution GmbH",
          "supplierArticleNumber": "NL-T14G5-32"
        },
        {
          "availableQuantity": 12,
          "currency": "EUR",
          "deliveryTimeDays": 2,
          "directOrderable": true,
          "distributorName": "Ingram Micro",
          "isDefault": false,
          "microtechAddressNo": 70010,
          "purchasePrice": 1067.5,
          "source": "ingram",
          "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10",
          "supplierAddressName": "Ingram Micro Distribution GmbH",
          "supplierArticleNumber": "7J0815"
        }
      ],
      "title": "Lenovo ThinkPad T14 Gen 5, 14\" WUXGA, Core Ultra 7 155U, 32 GB, 1 TB SSD, Win 11 Pro",
      "totalAvailableQuantity": 37,
      "unit": "Stk",
      "weight": 1.37
    }
  ],
  "total": 1,
  "warnings": [
    {
      "code": "",
      "connector": "amazon",
      "message": "Amazon Business antwortet nicht (Zeitüberschreitung nach 10 s)."
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/itsp/articles/search' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"options":{"connectors":["egis","ingram","amazon"],"maxResults":20,"onlyInStock":true},"query":"Lenovo ThinkPad T14"}'
```

## Load full details of selected articles (tenant:trade:purchasing:read)

`POST /api/trade/v1/itsp/articles/details`

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

Hydrates articles from a search answer with descriptions, features and all supplier offers.

### Request body

`application/json` (required)

- `articles` (array of NormalizedArticle, required)
  - `bestPurchasePrice` (number): Lowest purchase price of all supplier offers.
  - `canonicalMpn` (string): Manufacturer part number normalized for matching.
  - `currency` (string): Currency (ISO 4217).
  - `description` (string): Description of the article.
  - `descriptions` (array of object): Every text the catalogs have for the article.
    - `recommended` (boolean): The catalog flags the text as recommended.
    - `source` (string): Catalog of the text, e.g. `CNET`, `ICECAT`, `EGIS`.
    - `text` (string): The text.
    - `title` (string): Title of the text, e.g. `Marketing-Text (CNET)`.
    - `type` (string): `main`, `marketing`, `short_summary`, `long_summary` or `short_desc`. (one of `main`, `marketing`, `short_summary`, `long_summary`, `short_desc`)
  - `ean` (string): EAN (GTIN) of the article.
  - `existingArticleId` (string): Masterdata id of the existing article.
  - `existingArticleNumber` (string): Article number of the article that exists in masterdata already.
  - `features` (array of object): Technical features of the article.
    - `name` (string): Name of the feature.
    - `value` (string): Value of the feature.
  - `fldSerienNrKz` (boolean): Serial number tracked.
  - `height` (number): Height of the article.
  - `id` (string): Id of the article in the merged search result.
  - `imageUrl` (string): Link to a product image.
  - `inStock` (boolean): Stock confirmed without a quantity.
  - `length` (number): Length of the article.
  - `manufacturerCode` (string): Manufacturer code in masterdata.
  - `manufacturerId` (string): The catalog's id of the manufacturer.
  - `manufacturerName` (string): Name of the manufacturer.
  - `marketingText` (string): Marketing text of the article.
  - `microtechArticleNumber` (string): Article number of the article in the ERP, when it exists there.
  - `microtechStatus` (string): Whether the article exists in masterdata. (one of `NOT_FOUND`, `EXISTS`, `MULTIPLE_MATCHES`, `REQUIRES_MANUAL_MAPPING`)
  - `mpn` (string): Manufacturer part number.
  - `productGroup` (string): Name of the product group.
  - `productGroupNumber` (string): Number of the product group in masterdata.
  - `requiresManualMapping` (boolean): The manufacturer could not be mapped to masterdata automatically.
  - `searchTerm` (string): Search term (Suchbegriff) of the article.
  - `shortDescription` (string): Short description of the article.
  - `source` (string): Catalog the article came from; comma-separated when several had it.
  - `sourceArticleId` (string): The catalog's id of the article.
  - `sourceIdentifiers` (object): Connector → its article id.
  - `suppliers` (array of SupplierArticle): Supplier offers of the article.
    - `availableQuantity` (number): Quantity available at the distributor.
    - `currency` (string): Currency of the purchase price (ISO 4217).
    - `deliveryTimeDays` (integer): Delivery time in days.
    - `directOrderable` (boolean): The article can be ordered from the distributor through trade.
    - `distributorId` (string): EGIS id of the distributor.
    - `distributorName` (string): Name of the distributor.
    - `isDefault` (boolean): This supplier is the default supplier of the article.
    - `microtechAddressNo` (integer): Address number of the supplier in masterdata.
    - `purchasePrice` (number): Net purchase price.
    - `source` (string): Catalog of the offer (`egis`, `ingram`, …).
    - `supplierAddressId` (string): Masterdata address the distributor is assigned to.
    - `supplierAddressName` (string): Name of the masterdata supplier address of the distributor.
    - `supplierArticleNumber` (string): The distributor's article number.
  - `title` (string): Title of the article.
  - `totalAvailableQuantity` (number): Quantity available across all distributors.
  - `unit` (string): Unit of measure.
  - `weight` (number): Weight of the article.
  - `width` (number): Width of the article.

Example:

```json
{
  "articles": [
    {
      "bestPurchasePrice": 1049,
      "canonicalMpn": "21MC0012GE",
      "currency": "EUR",
      "descriptions": [
        {
          "recommended": true,
          "source": "EGIS",
          "text": "Business-Notebook mit 14-Zoll-WUXGA-Display, Intel Core Ultra 7 155U, 32 GB RAM und 1 TB SSD.",
          "title": "Produktbeschreibung (EGIS)",
          "type": "main"
        }
      ],
      "ean": "0197529876543",
      "features": [
        {
          "name": "Bildschirmdiagonale",
          "value": "35,6 cm (14\")"
        },
        {
          "name": "Prozessor",
          "value": "Intel Core Ultra 7 155U"
        }
      ],
      "fldSerienNrKz": true,
      "id": "art-21MC0012GE",
      "inStock": true,
      "manufacturerCode": "LNV",
      "manufacturerName": "Lenovo",
      "microtechStatus": "NOT_FOUND",
      "mpn": "21MC0012GE",
      "productGroup": "Notebooks",
      "productGroupNumber": "120",
      "requiresManualMapping": false,
      "searchTerm": "THINKPAD T14 G5",
      "shortDescription": "Lenovo ThinkPad T14 Gen 5",
      "source": "egis,ingram",
      "sourceArticleId": "PCS512377",
      "sourceIdentifiers": {
        "egis": "PCS512377",
        "ingram": "7J0815"
      },
      "suppliers": [
        {
          "availableQuantity": 25,
          "currency": "EUR",
          "deliveryTimeDays": 1,
          "directOrderable": true,
          "distributorId": "70044",
          "distributorName": "Nordlicht IT-Distribution GmbH",
          "isDefault": true,
          "microtechAddressNo": 70001,
          "purchasePrice": 1049,
          "source": "egis",
          "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
          "supplierAddressName": "Nordlicht IT-Distribution GmbH",
          "supplierArticleNumber": "NL-T14G5-32"
        },
        {
          "availableQuantity": 12,
          "currency": "EUR",
          "deliveryTimeDays": 2,
          "directOrderable": true,
          "distributorName": "Ingram Micro",
          "isDefault": false,
          "microtechAddressNo": 70010,
          "purchasePrice": 1067.5,
          "source": "ingram",
          "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10",
          "supplierAddressName": "Ingram Micro Distribution GmbH",
          "supplierArticleNumber": "7J0815"
        }
      ],
      "title": "Lenovo ThinkPad T14 Gen 5, 14\" WUXGA, Core Ultra 7 155U, 32 GB, 1 TB SSD, Win 11 Pro",
      "totalAvailableQuantity": 37,
      "unit": "Stk",
      "weight": 1.37
    }
  ]
}
```

### Responses

- **200** Details (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `articles` (array of NormalizedArticle)
  - `bestPurchasePrice` (number): Lowest purchase price of all supplier offers.
  - `canonicalMpn` (string): Manufacturer part number normalized for matching.
  - `currency` (string): Currency (ISO 4217).
  - `description` (string): Description of the article.
  - `descriptions` (array of object): Every text the catalogs have for the article.
    - `recommended` (boolean): The catalog flags the text as recommended.
    - `source` (string): Catalog of the text, e.g. `CNET`, `ICECAT`, `EGIS`.
    - `text` (string): The text.
    - `title` (string): Title of the text, e.g. `Marketing-Text (CNET)`.
    - `type` (string): `main`, `marketing`, `short_summary`, `long_summary` or `short_desc`. (one of `main`, `marketing`, `short_summary`, `long_summary`, `short_desc`)
  - `ean` (string): EAN (GTIN) of the article.
  - `existingArticleId` (string): Masterdata id of the existing article.
  - `existingArticleNumber` (string): Article number of the article that exists in masterdata already.
  - `features` (array of object): Technical features of the article.
    - `name` (string): Name of the feature.
    - `value` (string): Value of the feature.
  - `fldSerienNrKz` (boolean): Serial number tracked.
  - `height` (number): Height of the article.
  - `id` (string): Id of the article in the merged search result.
  - `imageUrl` (string): Link to a product image.
  - `inStock` (boolean): Stock confirmed without a quantity.
  - `length` (number): Length of the article.
  - `manufacturerCode` (string): Manufacturer code in masterdata.
  - `manufacturerId` (string): The catalog's id of the manufacturer.
  - `manufacturerName` (string): Name of the manufacturer.
  - `marketingText` (string): Marketing text of the article.
  - `microtechArticleNumber` (string): Article number of the article in the ERP, when it exists there.
  - `microtechStatus` (string): Whether the article exists in masterdata. (one of `NOT_FOUND`, `EXISTS`, `MULTIPLE_MATCHES`, `REQUIRES_MANUAL_MAPPING`)
  - `mpn` (string): Manufacturer part number.
  - `productGroup` (string): Name of the product group.
  - `productGroupNumber` (string): Number of the product group in masterdata.
  - `requiresManualMapping` (boolean): The manufacturer could not be mapped to masterdata automatically.
  - `searchTerm` (string): Search term (Suchbegriff) of the article.
  - `shortDescription` (string): Short description of the article.
  - `source` (string): Catalog the article came from; comma-separated when several had it.
  - `sourceArticleId` (string): The catalog's id of the article.
  - `sourceIdentifiers` (object): Connector → its article id.
  - `suppliers` (array of SupplierArticle): Supplier offers of the article.
    - `availableQuantity` (number): Quantity available at the distributor.
    - `currency` (string): Currency of the purchase price (ISO 4217).
    - `deliveryTimeDays` (integer): Delivery time in days.
    - `directOrderable` (boolean): The article can be ordered from the distributor through trade.
    - `distributorId` (string): EGIS id of the distributor.
    - `distributorName` (string): Name of the distributor.
    - `isDefault` (boolean): This supplier is the default supplier of the article.
    - `microtechAddressNo` (integer): Address number of the supplier in masterdata.
    - `purchasePrice` (number): Net purchase price.
    - `source` (string): Catalog of the offer (`egis`, `ingram`, …).
    - `supplierAddressId` (string): Masterdata address the distributor is assigned to.
    - `supplierAddressName` (string): Name of the masterdata supplier address of the distributor.
    - `supplierArticleNumber` (string): The distributor's article number.
  - `title` (string): Title of the article.
  - `totalAvailableQuantity` (number): Quantity available across all distributors.
  - `unit` (string): Unit of measure.
  - `weight` (number): Weight of the article.
  - `width` (number): Width of the article.
- `warnings` (array of ConnectorWarning)
  - `code` (string): Machine-readable kind of the warning; empty for other failures (the message names them). Known values: `PRICES_UNAVAILABLE` (the connector could not answer prices and availability; its offers are missing, article data it read is still returned).
  - `connector` (string): The connector that did not answer fully.
  - `message` (string): What went wrong.

Example 200 answer:

```json
{
  "articles": [
    {
      "bestPurchasePrice": 1049,
      "canonicalMpn": "21MC0012GE",
      "currency": "EUR",
      "descriptions": [
        {
          "recommended": true,
          "source": "EGIS",
          "text": "Business-Notebook mit 14-Zoll-WUXGA-Display, Intel Core Ultra 7 155U, 32 GB RAM und 1 TB SSD.",
          "title": "Produktbeschreibung (EGIS)",
          "type": "main"
        }
      ],
      "ean": "0197529876543",
      "features": [
        {
          "name": "Bildschirmdiagonale",
          "value": "35,6 cm (14\")"
        },
        {
          "name": "Prozessor",
          "value": "Intel Core Ultra 7 155U"
        }
      ],
      "fldSerienNrKz": true,
      "id": "art-21MC0012GE",
      "inStock": true,
      "manufacturerCode": "LNV",
      "manufacturerName": "Lenovo",
      "microtechStatus": "NOT_FOUND",
      "mpn": "21MC0012GE",
      "productGroup": "Notebooks",
      "productGroupNumber": "120",
      "requiresManualMapping": false,
      "searchTerm": "THINKPAD T14 G5",
      "shortDescription": "Lenovo ThinkPad T14 Gen 5",
      "source": "egis,ingram",
      "sourceArticleId": "PCS512377",
      "sourceIdentifiers": {
        "egis": "PCS512377",
        "ingram": "7J0815"
      },
      "suppliers": [
        {
          "availableQuantity": 25,
          "currency": "EUR",
          "deliveryTimeDays": 1,
          "directOrderable": true,
          "distributorId": "70044",
          "distributorName": "Nordlicht IT-Distribution GmbH",
          "isDefault": true,
          "microtechAddressNo": 70001,
          "purchasePrice": 1049,
          "source": "egis",
          "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
          "supplierAddressName": "Nordlicht IT-Distribution GmbH",
          "supplierArticleNumber": "NL-T14G5-32"
        },
        {
          "availableQuantity": 12,
          "currency": "EUR",
          "deliveryTimeDays": 2,
          "directOrderable": true,
          "distributorName": "Ingram Micro",
          "isDefault": false,
          "microtechAddressNo": 70010,
          "purchasePrice": 1067.5,
          "source": "ingram",
          "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10",
          "supplierAddressName": "Ingram Micro Distribution GmbH",
          "supplierArticleNumber": "7J0815"
        }
      ],
      "title": "Lenovo ThinkPad T14 Gen 5, 14\" WUXGA, Core Ultra 7 155U, 32 GB, 1 TB SSD, Win 11 Pro",
      "totalAvailableQuantity": 37,
      "unit": "Stk",
      "weight": 1.37
    }
  ],
  "warnings": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/itsp/articles/details' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"articles":[{"bestPurchasePrice":1049,"canonicalMpn":"21MC0012GE","currency":"EUR","descriptions":[{"recommended":true,"source":"EGIS","text":"Business-Notebook mit 14-Zoll-WUXGA-Display, Intel Core Ultra 7 155U, 32 GB RAM und 1 TB SSD.","title":"Produktbeschreibung (EGIS)","type":"main"}],"ean":"0197529876543","features":[{"name":"Bildschirmdiagonale","value":"35,6 cm (14\")"},{"name":"Prozessor","value":"Intel Core Ultra 7 155U"}],"fldSerienNrKz":true,"id":"art-21MC0012GE","inStock":true,"manufacturerCode":"LNV","manufacturerName":"Lenovo","microtechStatus":"NOT_FOUND","mpn":"21MC0012GE","productGroup":"Notebooks","productGroupNumber":"120","requiresManualMapping":false,"searchTerm":"THINKPAD T14 G5","shortDescription":"Lenovo ThinkPad T14 Gen 5","source":"egis,ingram","sourceArticleId":"PCS512377","sourceIdentifiers":{"egis":"PCS512377","ingram":"7J0815"},"suppliers":[{"availableQuantity":25,"currency":"EUR","deliveryTimeDays":1,"directOrderable":true,"distributorId":"70044","distributorName":"Nordlicht IT-Distribution GmbH","isDefault":true,"microtechAddressNo":70001,"purchasePrice":1049,"source":"egis","supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01","supplierAddressName":"Nordlicht IT-Distribution GmbH","supplierArticleNumber":"NL-T14G5-32"},{"availableQuantity":12,"currency":"EUR","deliveryTimeDays":2,"directOrderable":true,"distributorName":"Ingram Micro","isDefault":false,"microtechAddressNo":70010,"purchasePrice":1067.5,"source":"ingram","supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10","supplierAddressName":"Ingram Micro Distribution GmbH","supplierArticleNumber":"7J0815"}],"title":"Lenovo ThinkPad T14 Gen 5, 14\" WUXGA, Core Ultra 7 155U, 32 GB, 1 TB SSD, Win 11 Pro","totalAvailableQuantity":37,"unit":"Stk","weight":1.37}]}'
```

## Propose title, texts and product group for an article (tenant:trade:purchasing:read)

`POST /api/trade/v1/itsp/articles/enrich`

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

Rule-based; with `useAi` also through the AI service unless the tenant switched AI enrichment off. Never fails on AI errors (falls back to the rules).

### Request body

`application/json` (required)

- `article` (NormalizedArticle, required)
  - `bestPurchasePrice` (number): Lowest purchase price of all supplier offers.
  - `canonicalMpn` (string): Manufacturer part number normalized for matching.
  - `currency` (string): Currency (ISO 4217).
  - `description` (string): Description of the article.
  - `descriptions` (array of object): Every text the catalogs have for the article.
    - `recommended` (boolean): The catalog flags the text as recommended.
    - `source` (string): Catalog of the text, e.g. `CNET`, `ICECAT`, `EGIS`.
    - `text` (string): The text.
    - `title` (string): Title of the text, e.g. `Marketing-Text (CNET)`.
    - `type` (string): `main`, `marketing`, `short_summary`, `long_summary` or `short_desc`. (one of `main`, `marketing`, `short_summary`, `long_summary`, `short_desc`)
  - `ean` (string): EAN (GTIN) of the article.
  - `existingArticleId` (string): Masterdata id of the existing article.
  - `existingArticleNumber` (string): Article number of the article that exists in masterdata already.
  - `features` (array of object): Technical features of the article.
    - `name` (string): Name of the feature.
    - `value` (string): Value of the feature.
  - `fldSerienNrKz` (boolean): Serial number tracked.
  - `height` (number): Height of the article.
  - `id` (string): Id of the article in the merged search result.
  - `imageUrl` (string): Link to a product image.
  - `inStock` (boolean): Stock confirmed without a quantity.
  - `length` (number): Length of the article.
  - `manufacturerCode` (string): Manufacturer code in masterdata.
  - `manufacturerId` (string): The catalog's id of the manufacturer.
  - `manufacturerName` (string): Name of the manufacturer.
  - `marketingText` (string): Marketing text of the article.
  - `microtechArticleNumber` (string): Article number of the article in the ERP, when it exists there.
  - `microtechStatus` (string): Whether the article exists in masterdata. (one of `NOT_FOUND`, `EXISTS`, `MULTIPLE_MATCHES`, `REQUIRES_MANUAL_MAPPING`)
  - `mpn` (string): Manufacturer part number.
  - `productGroup` (string): Name of the product group.
  - `productGroupNumber` (string): Number of the product group in masterdata.
  - `requiresManualMapping` (boolean): The manufacturer could not be mapped to masterdata automatically.
  - `searchTerm` (string): Search term (Suchbegriff) of the article.
  - `shortDescription` (string): Short description of the article.
  - `source` (string): Catalog the article came from; comma-separated when several had it.
  - `sourceArticleId` (string): The catalog's id of the article.
  - `sourceIdentifiers` (object): Connector → its article id.
  - `suppliers` (array of SupplierArticle): Supplier offers of the article.
    - `availableQuantity` (number): Quantity available at the distributor.
    - `currency` (string): Currency of the purchase price (ISO 4217).
    - `deliveryTimeDays` (integer): Delivery time in days.
    - `directOrderable` (boolean): The article can be ordered from the distributor through trade.
    - `distributorId` (string): EGIS id of the distributor.
    - `distributorName` (string): Name of the distributor.
    - `isDefault` (boolean): This supplier is the default supplier of the article.
    - `microtechAddressNo` (integer): Address number of the supplier in masterdata.
    - `purchasePrice` (number): Net purchase price.
    - `source` (string): Catalog of the offer (`egis`, `ingram`, …).
    - `supplierAddressId` (string): Masterdata address the distributor is assigned to.
    - `supplierAddressName` (string): Name of the masterdata supplier address of the distributor.
    - `supplierArticleNumber` (string): The distributor's article number.
  - `title` (string): Title of the article.
  - `totalAvailableQuantity` (number): Quantity available across all distributors.
  - `unit` (string): Unit of measure.
  - `weight` (number): Weight of the article.
  - `width` (number): Width of the article.
- `productGroups` (array of ProductGroup): Product groups the proposal may choose from.
  - `name` (string): Name of the product group.
  - `number` (string): Number of the product group in masterdata.
- `useAi` (boolean)

Example:

```json
{
  "article": {
    "bestPurchasePrice": 1049,
    "canonicalMpn": "21MC0012GE",
    "currency": "EUR",
    "descriptions": [
      {
        "recommended": true,
        "source": "EGIS",
        "text": "Business-Notebook mit 14-Zoll-WUXGA-Display, Intel Core Ultra 7 155U, 32 GB RAM und 1 TB SSD.",
        "title": "Produktbeschreibung (EGIS)",
        "type": "main"
      }
    ],
    "ean": "0197529876543",
    "features": [
      {
        "name": "Bildschirmdiagonale",
        "value": "35,6 cm (14\")"
      },
      {
        "name": "Prozessor",
        "value": "Intel Core Ultra 7 155U"
      }
    ],
    "fldSerienNrKz": true,
    "id": "art-21MC0012GE",
    "inStock": true,
    "manufacturerCode": "LNV",
    "manufacturerName": "Lenovo",
    "microtechStatus": "NOT_FOUND",
    "mpn": "21MC0012GE",
    "productGroup": "Notebooks",
    "productGroupNumber": "120",
    "requiresManualMapping": false,
    "searchTerm": "THINKPAD T14 G5",
    "shortDescription": "Lenovo ThinkPad T14 Gen 5",
    "source": "egis,ingram",
    "sourceArticleId": "PCS512377",
    "sourceIdentifiers": {
      "egis": "PCS512377",
      "ingram": "7J0815"
    },
    "suppliers": [
      {
        "availableQuantity": 25,
        "currency": "EUR",
        "deliveryTimeDays": 1,
        "directOrderable": true,
        "distributorId": "70044",
        "distributorName": "Nordlicht IT-Distribution GmbH",
        "isDefault": true,
        "microtechAddressNo": 70001,
        "purchasePrice": 1049,
        "source": "egis",
        "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
        "supplierAddressName": "Nordlicht IT-Distribution GmbH",
        "supplierArticleNumber": "NL-T14G5-32"
      },
      {
        "availableQuantity": 12,
        "currency": "EUR",
        "deliveryTimeDays": 2,
        "directOrderable": true,
        "distributorName": "Ingram Micro",
        "isDefault": false,
        "microtechAddressNo": 70010,
        "purchasePrice": 1067.5,
        "source": "ingram",
        "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10",
        "supplierAddressName": "Ingram Micro Distribution GmbH",
        "supplierArticleNumber": "7J0815"
      }
    ],
    "title": "Lenovo ThinkPad T14 Gen 5, 14\" WUXGA, Core Ultra 7 155U, 32 GB, 1 TB SSD, Win 11 Pro",
    "totalAvailableQuantity": 37,
    "unit": "Stk",
    "weight": 1.37
  },
  "productGroups": [
    {
      "name": "Notebooks",
      "number": "120"
    },
    {
      "name": "Monitore",
      "number": "130"
    }
  ],
  "useAi": true
}
```

### Responses

- **200** Proposal (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `catalogSource` (string): Catalog the proposal is based on.
- `description` (string): Suggested Beschreibung (long text).
- `productGroup` (string): Name of the product group.
- `productGroupNumber` (string): Number of the product group in masterdata.
- `searchTerm` (string): Search term (Suchbegriff) of the article.
- `shortDescription` (string): Suggested Kurzbezeichnung (max. 80 characters).
- `title` (string): Suggested Bezeichnung (max. 2000 characters).

Example 200 answer:

```json
{
  "catalogSource": "EGIS",
  "description": "Robustes 14-Zoll-Business-Notebook mit Intel Core Ultra 7, 32 GB Arbeitsspeicher und 1 TB SSD – für den mobilen Einsatz in Vertrieb und Technik.",
  "productGroup": "Notebooks",
  "productGroupNumber": "120",
  "searchTerm": "THINKPAD T14 G5",
  "shortDescription": "Lenovo ThinkPad T14 Gen 5 Ultra 7 32 GB 1 TB",
  "title": "Lenovo ThinkPad T14 Gen 5 – 14\" WUXGA IPS, Intel Core Ultra 7 155U, 32 GB RAM, 1 TB SSD, Windows 11 Pro"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/itsp/articles/enrich' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"article":{"bestPurchasePrice":1049,"canonicalMpn":"21MC0012GE","currency":"EUR","descriptions":[{"recommended":true,"source":"EGIS","text":"Business-Notebook mit 14-Zoll-WUXGA-Display, Intel Core Ultra 7 155U, 32 GB RAM und 1 TB SSD.","title":"Produktbeschreibung (EGIS)","type":"main"}],"ean":"0197529876543","features":[{"name":"Bildschirmdiagonale","value":"35,6 cm (14\")"},{"name":"Prozessor","value":"Intel Core Ultra 7 155U"}],"fldSerienNrKz":true,"id":"art-21MC0012GE","inStock":true,"manufacturerCode":"LNV","manufacturerName":"Lenovo","microtechStatus":"NOT_FOUND","mpn":"21MC0012GE","productGroup":"Notebooks","productGroupNumber":"120","requiresManualMapping":false,"searchTerm":"THINKPAD T14 G5","shortDescription":"Lenovo ThinkPad T14 Gen 5","source":"egis,ingram","sourceArticleId":"PCS512377","sourceIdentifiers":{"egis":"PCS512377","ingram":"7J0815"},"suppliers":[{"availableQuantity":25,"currency":"EUR","deliveryTimeDays":1,"directOrderable":true,"distributorId":"70044","distributorName":"Nordlicht IT-Distribution GmbH","isDefault":true,"microtechAddressNo":70001,"purchasePrice":1049,"source":"egis","supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01","supplierAddressName":"Nordlicht IT-Distribution GmbH","supplierArticleNumber":"NL-T14G5-32"},{"availableQuantity":12,"currency":"EUR","deliveryTimeDays":2,"directOrderable":true,"distributorName":"Ingram Micro","isDefault":false,"microtechAddressNo":70010,"purchasePrice":1067.5,"source":"ingram","supplierAddressId":"6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d10","supplierAddressName":"Ingram Micro Distribution GmbH","supplierArticleNumber":"7J0815"}],"title":"Lenovo ThinkPad T14 Gen 5, 14\" WUXGA, Core Ultra 7 155U, 32 GB, 1 TB SSD, Win 11 Pro","totalAvailableQuantity":37,"unit":"Stk","weight":1.37},"productGroups":[{"name":"Notebooks","number":"120"},{"name":"Monitore","number":"130"}],"useAi":true}'
```

## Create the article in masterdata (tenant:masterdata:write)

`POST /api/trade/v1/itsp/articles/create`

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

Creates the article with its supplier conditions in masterdata, using the caller's token.
`articleNumber` (upper-case letters and digits, at most 25), `title`, `searchTerm`, `productGroup`
(number of an existing product group), `unit` and `fldSerienNrKz` are required (`400` with a
German message). An article that exists exactly once already answers `409`.

### Request body

`application/json` (required)

- `articleNumber` (string, required): Article number to create in masterdata. (max length 25)
- `fldSerienNrKz` (boolean, nullable, required): Serial number tracked; required.
- `productGroup` (string, required): Number of a masterdata product group.
- `salesPrice` (number, required): Net sales price (VK); required, may be 0.
- `searchTerm` (string, required): Search term (Suchbegriff) of the article. (max length 25)
- `shortDescription` (string, required): Kurzbezeichnung (shortName in masterdata): required, single line, max. 80 characters. (max length 80)
- `unit` (string, required): Unit of measure.
- `description` (string): Beschreibung: long text without length limit.
- `ean` (string): EAN (GTIN) of the article.
- `height` (number): Height of the article.
- `length` (number): Length of the article.
- `manufacturerName` (string): Name of the manufacturer.
- `mpn` (string): Manufacturer part number.
- `suppliers` (array of object): Supplier offers to store with the article.
  - `microtechAddressNo` (integer, required): Address number of the supplier in masterdata.
  - `currency` (string): ISO 4217; EUR when empty.
  - `isDefault` (boolean): This supplier is the default supplier of the article.
  - `purchasePrice` (number): Net purchase price.
  - `supplierArticleNumber` (string): The distributor's article number.
- `title` (string): Bezeichnung (name in masterdata): text of document lines, optional, max. 2000 characters. (max length 2000)
- `weight` (number): Weight of the article.
- `width` (number): Width of the article.

Example:

```json
{
  "articleNumber": "LNVT14G5",
  "ean": "0197529876543",
  "fldSerienNrKz": true,
  "manufacturerName": "Lenovo",
  "mpn": "21MC0012GE",
  "productGroup": "120",
  "salesPrice": 1349,
  "searchTerm": "THINKPAD T14 G5",
  "shortDescription": "Lenovo ThinkPad T14 Gen 5 Ultra 7 32 GB 1 TB",
  "suppliers": [
    {
      "currency": "EUR",
      "isDefault": true,
      "microtechAddressNo": 70001,
      "purchasePrice": 1049,
      "supplierArticleNumber": "NL-T14G5-32"
    }
  ],
  "title": "Lenovo ThinkPad T14 Gen 5 – 14\" WUXGA IPS, Intel Core Ultra 7 155U, 32 GB RAM, 1 TB SSD, Windows 11 Pro",
  "unit": "Stk",
  "weight": 1.37
}
```

### Responses

- **201** Created (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Masterdata refused the caller. (`application/json`)
- **409** The article exists already. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 201 answer:

- `articleNumber` (string): Article number created in masterdata.
- `id` (string): Masterdata article id.
- `message` (string): Message of masterdata.
- `status` (string): Outcome of the creation (`CREATED`). (one of `CREATED`)

Example 201 answer:

```json
{
  "articleNumber": "LNVT14G5",
  "id": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7e15",
  "message": "Artikel LNVT14G5 angelegt.",
  "status": "CREATED"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/itsp/articles/create' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"articleNumber":"LNVT14G5","ean":"0197529876543","fldSerienNrKz":true,"manufacturerName":"Lenovo","mpn":"21MC0012GE","productGroup":"120","salesPrice":1349,"searchTerm":"THINKPAD T14 G5","shortDescription":"Lenovo ThinkPad T14 Gen 5 Ultra 7 32 GB 1 TB","suppliers":[{"currency":"EUR","isDefault":true,"microtechAddressNo":70001,"purchasePrice":1049,"supplierArticleNumber":"NL-T14G5-32"}],"title":"Lenovo ThinkPad T14 Gen 5 – 14\" WUXGA IPS, Intel Core Ultra 7 155U, 32 GB RAM, 1 TB SSD, Windows 11 Pro","unit":"Stk","weight":1.37}'
```

## List the product groups of masterdata (tenant:trade:purchasing:read)

`GET /api/trade/v1/itsp/articles/product-groups`

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

### Responses

- **200** Product groups (`application/json`)
- **401** No valid session or bearer token (no body).
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `productGroups` (array of ProductGroup)
  - `name` (string): Name of the product group.
  - `number` (string): Number of the product group in masterdata.

Example 200 answer:

```json
{
  "productGroups": [
    {
      "name": "PCs",
      "number": "110"
    },
    {
      "name": "Notebooks",
      "number": "120"
    },
    {
      "name": "Monitore",
      "number": "130"
    },
    {
      "name": "Netzwerk",
      "number": "210"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/itsp/articles/product-groups' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the units of measure of masterdata (tenant:trade:purchasing:read)

`GET /api/trade/v1/itsp/articles/units`

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

### Responses

- **200** Units (`application/json`)
- **401** No valid session or bearer token (no body).
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)

Fields of the 200 answer:

- `units` (array of UnitOfMeasure)
  - `code` (string): UN/ECE unit code (e.g. `C62`).
  - `isUsed` (boolean): Articles in masterdata use the unit.
  - `name` (string): Name (e.g. `Stück`).
  - `shortName` (string): Short name (e.g. `Stk`).

Example 200 answer:

```json
{
  "units": [
    {
      "code": "C62",
      "isUsed": true,
      "name": "Stück",
      "shortName": "Stk"
    },
    {
      "code": "PK",
      "isUsed": true,
      "name": "Paket",
      "shortName": "Pak"
    },
    {
      "code": "HUR",
      "isUsed": true,
      "name": "Stunde",
      "shortName": "Std"
    },
    {
      "code": "MON",
      "isUsed": true,
      "name": "Monat",
      "shortName": "Mon"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/itsp/articles/units' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the tenant's EGIS shopping carts (tenant:egis-cart:write)

`GET /api/trade/v1/itsp/egis/carts`

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

Only the carts shared with all employees of the EGIS partner (name prefix `(global)`); one EBC login per tenant.

### Responses

- **200** Carts (`application/json`)
- **400** EGIS is not set up. (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `carts` (array of EgisCart)
  - `label` (string): Name without the `(global)` prefix.
  - `name` (string): Name in EGIS.

Example 200 answer:

```json
{
  "carts": [
    {
      "label": "Einkauf",
      "name": "(global) Einkauf"
    },
    {
      "label": "Projekt Alpenhotel",
      "name": "(global) Projekt Alpenhotel"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/itsp/egis/carts' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Delete an EGIS shopping cart (tenant:egis-cart:write)

`DELETE /api/trade/v1/itsp/egis/carts`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `name` | query | string | yes | Cart name without the `(global)` prefix. |

### Responses

- **204** Deleted
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/trade/v1/itsp/egis/carts?name=Einkauf' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get an EGIS shopping cart with positions and totals per distributor (tenant:egis-cart:write)

`GET /api/trade/v1/itsp/egis/carts/detail`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `name` | query | string | yes | Cart name without the `(global)` prefix. |

### Responses

- **200** Cart (`application/json`)
- **400** Invalid name, unknown cart or EGIS not set up. (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `label` (string): Name without the `(global)` prefix.
- `name` (string): Name in EGIS.
- `additionalCharges` (number): Freight, minimum-order and small-quantity charges of all distributors.
- `distributors` (array of object): Totals per distributor for an online order.
  - `distributorId` (string): EGIS id of the distributor.
  - `distributorName` (string): Name of the distributor.
  - `freightAbsorptionLimit` (number): Order value from which no freight is charged.
  - `freightCharge` (number): Freight charge.
  - `minimumOrderValue` (number): Minimum order value of the distributor.
  - `positions` (integer): Number of positions of the distributor.
  - `productTotal` (number): Total of the articles of the distributor.
  - `smallQuantitiesMarkup` (number): Small-quantity markup of the distributor.
  - `total` (number): Total of the distributor including its charges.
- `items` (array of object): Positions of the cart.
  - `availableQuantity` (integer): Quantity available at the distributor.
  - `comment` (string): Comment on the position.
  - `currency` (string): Currency (ISO 4217).
  - `description` (string): Description of the article.
  - `distributorId` (string): EGIS id of the distributor.
  - `distributorName` (string): Name of the distributor.
  - `ean` (string): EAN (GTIN) of the article.
  - `eol` (boolean): The article is end of life.
  - `manufacturerName` (string): Name of the manufacturer.
  - `mpn` (string): Manufacturer part number.
  - `pcsNumber` (string): EGIS PCS article number.
  - `purchasePrice` (number): Net purchase price.
  - `quantity` (integer): Quantity in the cart.
  - `supplierArticleNumber` (string): The distributor's article number.
- `positions` (integer): Number of positions in the cart.
- `total` (number): Total of the cart including the charges.

Example 200 answer:

```json
{
  "additionalCharges": 8.5,
  "distributors": [
    {
      "distributorId": "70044",
      "distributorName": "Nordlicht IT-Distribution GmbH",
      "freightAbsorptionLimit": 1500,
      "freightCharge": 8.5,
      "minimumOrderValue": 50,
      "positions": 2,
      "productTotal": 1264,
      "smallQuantitiesMarkup": 0,
      "total": 1272.5
    }
  ],
  "items": [
    {
      "availableQuantity": 140,
      "comment": "Mindestbestand Lager",
      "currency": "EUR",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "distributorId": "70044",
      "distributorName": "Nordlicht IT-Distribution GmbH",
      "ean": "4061234500076",
      "eol": false,
      "manufacturerName": "Nordlicht",
      "mpn": "HS-USB-ANC",
      "pcsNumber": "PCS400942",
      "purchasePrice": 79,
      "quantity": 16,
      "supplierArticleNumber": "NL-HS-USB-ANC"
    }
  ],
  "label": "Einkauf",
  "name": "(global) Einkauf",
  "positions": 2,
  "total": 1272.5
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/itsp/egis/carts/detail?name=Einkauf' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Put articles into an EGIS shopping cart (tenant:egis-cart:write)

`POST /api/trade/v1/itsp/egis/carts/items`

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

A cart that does not exist yet is created (`created`). EGIS answers per position; a refused position (no quantity, invalid quantity, no distributor article, distributor article end of life) has `added false` and a German `message` and does not fail the others.

### Request body

`application/json` (required)

- `cart` (string, required): Cart name without the `(global)` prefix (at most 26 characters); created when it does not exist.
- `lines` (array of object, required): Articles to put into the cart.
  - `quantity` (integer, required): Quantity to add.
  - `comment` (string): Comment on the cart position. (max length 200)
  - `description` (string): Description of the article. (max length 100)
  - `distributorId` (string): EGIS distributor number; empty lets EGIS choose.
  - `ean` (string): EAN (GTIN) of the article. (max length 15)
  - `mpn` (string): Manufacturer part number. (max length 50)
  - `pcsNumber` (string): EGIS PCS article number.
  - `supplierArticleNumber` (string): The distributor's article number. (max length 25)

Example:

```json
{
  "cart": "Einkauf",
  "lines": [
    {
      "comment": "Mindestbestand Lager",
      "distributorId": "70044",
      "pcsNumber": "PCS400942",
      "quantity": 16
    }
  ]
}
```

### Responses

- **200** Result per position (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** The configuration store is not available. (`application/json`)

Fields of the 200 answer:

- `label` (string): Name without the `(global)` prefix.
- `name` (string): Name in EGIS.
- `added` (integer): Number of lines added.
- `created` (boolean): The cart was new.
- `lines` (array of object): Outcome per requested line.
  - `added` (boolean): The line was added.
  - `message` (string): German reason of a refusal.
  - `pcsNumber` (string): EGIS PCS article number.
  - `position` (integer): Position of the line in the request.
  - `statusCode` (integer): 0 added, 2 no quantity, 3 invalid quantity, 4 no distributor article, 5 distributor article end of life. (one of `0`, `2`, `3`, `4`, `5`)
  - `supplierArticleNumber` (string): The distributor's article number.

Example 200 answer:

```json
{
  "added": 1,
  "created": false,
  "label": "Einkauf",
  "lines": [
    {
      "added": true,
      "pcsNumber": "PCS400942",
      "position": 1,
      "statusCode": 0,
      "supplierArticleNumber": "NL-HS-USB-ANC"
    }
  ],
  "name": "(global) Einkauf"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/itsp/egis/carts/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"cart":"Einkauf","lines":[{"comment":"Mindestbestand Lager","distributorId":"70044","pcsNumber":"PCS400942","quantity":16}]}'
```

