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