Sales documents and e-invoices (Trade)
Trade holds a tenant's commercial documents (Vorgänge): offers, order confirmations, delivery notes, invoices and
credit notes, purchase orders and inbound (supplier) invoices. Everything below is under https://api.mbcom.cloud/api/trade/v1;
every operation is in the Trade reference.
| Step | Operations | Permission |
|---|---|---|
| Offer and order | createOffer, createOrderConfirmation, updateTransaction, createTransactionRevision |
tenant:trade:sales:write |
| Deliver | deliverOrder, getOrderFulfilment |
tenant:trade:sales:write / :read |
| Invoice | draftInvoice, previewInvoiceIssue, issueInvoiceDraft, draftCreditNote |
draft: tenant:trade:sales:write, issue: tenant:trade:invoice:issue |
| E-invoice check | getInvoiceValidation, listInvoiceValidations |
tenant:trade:sales:read |
| Inbound invoices | listInboundInvoices, getInboundInvoice, releaseInboundInvoice, rejectInboundInvoice |
tenant:trade:inbound:read / :write / :approve |
One shape for every document
Every document is a transaction in one shape: a header (partner addressId, recipient, dates, payment terms,
totals) and items (the lines). transactionType names its type from the tenant's catalogue – OFFER, ORDER,
DELIVERY_NOTE, INVOICE, CREDIT_NOTE, PURCHASE_ORDER, INBOUND_INVOICE and the tenant's own types; read it
with listTransactionTypes instead of assuming more than these. The generic
routes (listTransactions, getTransaction,
createTransaction, updateTransaction)
work on every type; the permission follows the type: tenant:trade:sales:* for sales documents,
tenant:trade:purchasing:* for purchasing and tenant:trade:inbound:* for inbound invoices.
- Totals (
netTotal,taxTotal,grossTotal) are computed from the lines when a document is saved; you never send them. - Payment terms are a snapshot taken on create: the partner's terms from master data, else the tenant default.
versionandpredecessorIdare revisions of one document (createTransactionRevisioncopies it as versionn+1inDRAFT);sourceTransactionIdis the document this one was made from (offer → order → delivery note → invoice).PUTreplaces the stored document: send the whole document with itsitemson everyupdateTransaction. There is no optimistic locking in trade.- Every change is written to the document's protocol (
listTransactionProtocol).
Sales statuses are DRAFT, SENT, ACCEPTED, EXPIRED, REVOKED and CONVERTED; delivery notes made from an
order are DELIVERED or CANCELLED, issued invoices and credit notes ISSUED.
Offers and orders
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/offers' \
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-d '{
"addressId": "10042",
"recipientCompany": "Muster GmbH",
"validUntil": "2026-12-31T00:00:00Z",
"items": [
{ "name": "Notebook 14\"", "articleNumber": "NB-1400", "quantity": 3, "unit": "Stk", "unitPriceNet": 1149.00, "taxRate": 19 },
{ "name": "Einrichtung", "quantity": 2, "unit": "h", "unitPriceNet": 95.00, "taxRate": 19 }
]
}'
createOffer is createTransaction with transactionType: OFFER; it answers
201 with the offer, its number (the type's prefix) and the computed totals. opportunityId links it to a
CRM opportunity. Without a status the document is a DRAFT.
When the customer orders, create the order with
createOrderConfirmation (transactionType: ORDER) and the offer's id as
sourceTransactionId. An order is delivered and invoiced only once it is confirmed: create it with status: SENT or
set the status with updateTransaction – a DRAFT order answers
409 order_not_confirmed below.
Deliver an order
deliverOrder (POST /sales/order-confirmations/{id}/delivery-notes) creates a
delivery note for the newest revision of the order. An empty body delivers everything still open; lines deliver part
of it:
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/order-confirmations/7d1e…/delivery-notes' \
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-d '{"deliveryDate": "2026-11-20T00:00:00Z", "lines": [{"orderLineId": "4b0c…", "quantity": 2}]}'
The note is numbered gaplessly (LS-2026-00017), its lines point to the order lines (sourceLineId) and the stock is
booked out in the same transaction. A line is never delivered beyond its ordered quantity: 409 over_delivery
names details.lineId, open and requested; nothing_to_deliver when everything is delivered.
getOrderFulfilment shows the delivered and invoiced quantity of every order
line, cancelSalesDeliveryNote cancels a delivery note.
Invoice and issue an XRechnung
Invoicing takes two steps: a draft without a number, then issuing it.
draftInvoicewithsourceIds: delivery notes of one customer and currency (a collective invoice) or one confirmed order (what is ordered and not invoiced yet, e.g. services). The draft has the placeholder numberENTWURF-<id>and statusDRAFT; its quantities count as invoiced until it is deleted, so a quantity is never drafted twice (409when nothing is left to invoice).previewInvoiceIssuenames in German what is still missing for an XRechnung: the tenant's company profile (address, VAT ID, IBAN, invoice contact) and the customer's master data address and invoice e-mail.getInvoiceSheetshows the invoice as the customer reads it.issueInvoiceDraftissues it in one database transaction:
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/invoices/2c9f…/issue' \
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-d '{"version": 1, "send": true}'
Issuing takes the next gapless number (RE-2026-00042, credit notes GS-…), dates the invoice today, writes an
XRechnung 3.0 (CII), validates it with the KoSIT rules, archives the XML in the DMS
(typeData.einvoice) and, with send: true, mails it through comms to the customer's invoice e-mail (or
recipient). Nothing is numbered when it fails:
- 422
not_ready– facts are missing;details.problemslists them (the same as the preview). - 422
einvoice_invalid– the XRechnung fails the KoSIT rules;details.findingslists the findings. - 409 – the document is no draft any more, or it changed since the
versionyou sent.
An issued invoice is never changed again (409 issued_document), and ISSUED is set only by issuing (409 issue_only). Correct it with a credit note: draftCreditNote drafts one for the
given invoice lines (or everything not credited yet), issued the same way with XRechnung type 381.
getInvoiceValidation returns the e-invoice check of an issued invoice with
all findings, listInvoiceValidations every check of the tenant.
Drafts another module made (numberPending: true, e.g. the project invoices of desk) are issued with
releaseTransaction (tenant:trade:invoice:issue), which gives them the next
gapless number.
Invoices you issue yourself
If your system writes the invoices (an ERP or a shop), record them with
issueInvoice (POST /invoices/issue, tenant:trade:invoice:issue) with
invoiceNumber, addressId, the totals and lines, and the e-invoice as eInvoice: {content, fileName} (base64
XRechnung or ZUGFeRD/Factur-X XML, CII or UBL, or a hybrid PDF; at most 10 MB). When the customer's master data asks
for an e-invoice, it is required (422 einvoice_required; an XRechnung customer also needs a Leitweg-ID,
eInvoiceBuyerRef: 422 leitweg_id_required). The file is scanned for malware (422 malware) and validated
against the KoSIT rules; whether an invalid file is refused (422 einvoice_invalid with details.report) or only
reported depends on the tenant's setting. 503 (scan_unavailable, einvoice_unavailable) means the check cannot
run now: retry later.
Inbound e-invoices
Supplier invoices arrive as DMS documents – by mail or upload – and trade picks them up on its own. To
process a document you uploaded yourself, call createInboundInvoice with its
dmsDocumentId (idempotent per document). Processing runs in the background: the answer carries processing; read
the invoice with getInboundInvoice until processing is gone.
Trade reads the e-invoice XML (sourceKind XRECHNUNG_CII, XRECHNUNG_UBL, ZUGFERD) or, for other PDFs, OCR and AI
extraction (PDF_OCR), assigns the supplier from master data and matches the invoice against purchase orders and goods
receipts. Its status moves RECEIVED → OCR_DONE → EXTRACTED → MATCHED | DISCREPANCY | DUPLICATE, then IN_REVIEW,
RELEASED or REJECTED (FAILED when processing failed, with error).
- Lock reasons (
lockReasons:PREISABWEICHUNG,MENGENABWEICHUNG,DUPLIKAT,FEHLENDER_LIEFERANT, …) say why the invoice may not be released as it is;isBlocking: trueones block the release. updateInboundInvoicecorrects it during review (matched again);resolveInboundInvoiceLockReasonaccepts a blocking reason.releaseInboundInvoicereleases aMATCHED,DISCREPANCYorIN_REVIEWinvoice; with blocking reasons only withoverride: trueand acomment(else409 blocked).rejectInboundInvoiceneeds acomment. Both needtenant:trade:inbound:approve; a state that does not allow the action is409 invalid_state.getInboundInvoiceDocumentstreams the original file.
423 workflow_locked
A tenant can run approval workflows on trade documents (the Workflow module). While a workflow runs on a document, trade locks it against every other change, and writes answer:
HTTP/1.1 423 Locked
Content-Type: application/json
{"error": "Der Vorgang ist durch einen laufenden Workflow gesperrt.", "code": "workflow_locked"}
Every write on a single document can answer it – updating, revising, delivering, drafting and issuing invoices,
releasing or rejecting inbound invoices, sending purchase orders; the reference lists 423 on each of them. Reads are
never locked. The lock is recorded in metadata.workflow of the document (the workflow states OPEN and RETRYING_SYNC lock it); this
field belongs to the workflow module and is kept on every write, whatever you send.
How to handle it:
- Do not retry in a loop. The lock ends when people finish the workflow (approve, reject), which can take days –
unlike
429or5xxit is no transient error. Report it, park the change and try again after the document changed. - To know when, subscribe to
trade.transaction.updated(see Webhooks), or look the workflow up:listInstancesByObject(GET /api/workflow/v1/tasks/object/{transactionNumber}) lists the instances of a document with theirworkflowStateandcurrentStep. - If a workflow should apply your change, it is done in the workflow: the assignee changes the fields the step marks
editable when completing the task (
completeTask). - A document that stays locked although its workflow is over (state
RETRYING_SYNC: the write-back to trade is retried automatically) can be released by an administrator withresyncInstance(workflow:admin).
Events
For webhooks and flows, trade announces trade.transaction.created,
trade.transaction.updated, trade.transaction.deleted, trade.offer.created, trade.order.created,
trade.deliverynote.created, trade.invoice.issued and the inbound invoice states
(trade.inboundinvoice.extracted, …matched, …blocked, …released, …rejected, …). Events carry ids, numbers,
states and totals: read the document through the API for its lines.