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(orprice),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; defaultRechnung-<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:
{
"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:
codeiseinvoice_required,leitweg_id_required,malwareoreinvoice_invalid(withdetails.report). (application/json) - 500 Error (
application/json) - 503 The e-invoice cannot be checked now and is refused:
scan_unavailable(malware scan) oreinvoice_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(orprice),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:invoiceNumberis its id untilreleaseTransactionnumbers 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:
{
"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
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"}'