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