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