Entity · invoices

Invoice Schema

Schema-ID

invoice

Collection

invoices

Permissions

Leseninvoice_view
Anlegeninvoice_create
Änderninvoice_edit
Löscheninvoice_delete

Beziehungen

contractId → contract

Felder

Invoice Schema

invoices4 Permissions

Schema for validating Rechnung (invoice) entities

partyIduuiderforderlich

Customer party UUID

invoiceNumberstringoptional

Auto-generated sequence number (e.g. RE-2026-00001)

max 1000 Zeichenread-onlynullable

invoiceDatedateoptional

Invoice date

nullable

dueDatedateoptional

Payment due date

nullable

statusstringerforderlich

Invoice lifecycle status. POSTED = verbucht / revisionssicher festgeschrieben (lockedAt set). SENT = an Kunden versandt. Beide sind immutable.

Werte

DRAFTPOSTEDSENTPAIDPARTIALLY_PAIDOVERDUECANCELLEDCREDITED

Default: "DRAFT"

salesInvoiceTypestringoptional

Type of sales invoice (mirrors weclapp salesInvoiceOrigin). ADVANCE_PAYMENT=Anzahlung, PART_PAYMENT=Teilrechnung, FINAL=Schlussrechnung, RECURRING=wiederkehrend

Werte

STANDARDADVANCE_PAYMENTPART_PAYMENTPREPAYMENTFINALRECURRINGRETAIL

Default: "STANDARD"

bookingDatedateoptional

Buchungsdatum für DATEV (may differ from invoiceDate). Set on POSTED, drives the booking period.

nullable

lockedAtdatetimeoptional

When the invoice was locked (POSTED). After this the invoice is immutable except for status changes (PAID/OVERDUE/CANCELLED) and dunning fields.

read-onlynullable

lockedByuuidoptional

User UUID who posted (locked) the invoice

read-onlynullable

contentHashstringoptional

SHA-256 hash of canonical invoice content at lock time (GoBD revisionssicher). Verified on every read after POSTED.

max 128 Zeichenread-onlynullable

recordAddressSnapshotobjectoptional

Frozen invoice (recipient) address snapshot taken at POSTED. GoBD requires the address as printed on the original document.

read-onlynullable

namestringoptional

max 300 Zeichennullable

addressLine1stringoptional

max 300 Zeichennullable

addressLine2stringoptional

max 300 Zeichennullable

postalCodestringoptional

max 20 Zeichennullable

citystringoptional

max 200 Zeichennullable

statestringoptional

max 200 Zeichennullable

countryCodestringoptional

max 2 Zeichennullable

vatRegistrationNumberstringoptional

max 50 Zeichennullable

deliveryAddressSnapshotobjectoptional

Frozen delivery address snapshot (if different from invoice address)

read-onlynullable

namestringoptional

max 300 Zeichennullable

addressLine1stringoptional

max 300 Zeichennullable

addressLine2stringoptional

max 300 Zeichennullable

postalCodestringoptional

max 20 Zeichennullable

citystringoptional

max 200 Zeichennullable

statestringoptional

max 200 Zeichennullable

countryCodestringoptional

max 2 Zeichennullable

exchangeRatestringoptional

Exchange rate to EUR at invoice date. Only set when currency != EUR. Used for DATEV export.

Patternnullable

sourcestringoptional

How the invoice was created

Werte

MANUALPERFORMANCE_RECORDSALES_ORDERCONTRACTWECLAPPCREDIT_NOTEWHOLESALE_LICENSING

Default: "MANUAL"

customerTenantIdstringoptional

Customer tenant this invoice was generated for (only set when source=WHOLESALE_LICENSING).

PatternDefault: nullnullable

invoiceTypestringoptional

Werte

INVOICECREDIT_NOTE

Default: "INVOICE"

creditedInvoiceIdstringoptional

Original invoice ID (for credit notes)

PatternDefault: nullnullable

contractIdstringoptional

Source contract (if generated from recurring billing)

PatternDefault: nullnullable

dunningLevelintegeroptional

0 – 3Default: 0

lastDunningAtdatetimeoptional

Default: nullnullable

dunningBlockedUntildateoptional

Dunning suspended until this date

Default: nullnullable

projectIduuidoptional

Project this invoice bills (propagated from a per-project performance record). Null/absent for collective, per-ticket and legacy invoices.

read-onlynullable

performanceRecordIduuidoptional

Source performance record UUID (if generated from Leistungsnachweis)

nullable

titlestringoptional

Invoice title / subject

max 200 Zeichennullable

introTextstringoptional

Introductory text above positions

max 2000 Zeichennullable

closingTextstringoptional

Closing text below positions

max 2000 Zeichennullable

notesstringoptional

Internal notes (not printed)

max 2000 Zeichennullable

openTicketNotesobject[]optional

ADR 0146 — Snapshot copied from the source Leistungsnachweis: tickets that were still open at billing time but were unlocked via `ticket.billingOverride`. The invoice PDF renders a neutral "Hinweise"-section listing the affected ticket numbers; the internal reason is intentionally NOT propagated here.

Default: []nullable

ticketIduuiderforderlich

ticketNumberstringerforderlich

max 50 Zeichen

titlestringoptional

max 500 Zeichennullable

itemsobject[]optional

Invoice line items

Default: []

positionintegeroptional

≥ 1

descriptionstringerforderlich

max 500 Zeichen

unitstringoptional

max 20 Zeichennullable

quantitynumbererforderlich

≥ 0

unitPricestringerforderlich

Decimal string, e.g. "125.00"

vatRatestringoptional

VAT rate as percent string

Default: "19"

netAmountstringoptional

Computed: quantity * unitPrice

nullable

articleIdstringoptional

Article reference (local UUID or weclapp article id)

max 64 Zeichennullable

articleNumberstringoptional

Article SKU / weclapp articleNumber

nullable

itemTypestringoptional

Categorizes the line item origin

Werte

SERVICETRAVEL_DISTANCETRAVEL_TIMETRAVEL_OTHERFLAT_RATEEXPENSETICKETMATERIAL

nullable

materialBucketIduuidoptional

Source material bucket UUID (if generated from Materialkorb)

nullable

expenseIduuidoptional

Source expense UUID (EXPENSE lines of a per-project billing run)

nullable

positionIduuidoptional

Source project_position UUID (FLAT_RATE lines of a per-project billing run)

nullable

contractIdstringoptional

Default: nullnullable

contractItemIdstringoptional

Which contract position generated this invoice line

Default: nullnullable

timeRecordIdstringoptional

Source time_record UUID — set when this line was generated from a single booking (perEntry, ungrouped perTicket, or travel linked via trip.timeRecordId).

PatternDefault: nullnullable

timeRecordNumberstringoptional

Human-readable record number (e.g. TR-2026-00042) of the source time record. Snapshotted at build time so the UI can deep-link without an extra fetch.

max 50 ZeichenDefault: nullnullable

ticketIdstringoptional

Source ticket UUID — set when this line aggregates time records of one ticket (perTicket) or originates from a TR with referenceType=TICKET.

PatternDefault: nullnullable

accountCodestringoptional

DATEV revenue account (Erlöskonto, e.g. "8400"). Falls back to article.revenueAccountCode at posting time.

max 20 ZeichenDefault: nullnullable

costCenterIdstringoptional

Cost center UUID (Kostenstelle) for DATEV

PatternDefault: nullnullable

pricedAtstringoptional

ADR 0415 — date (YYYY-MM-DD) at which the base rate of this line was resolved (copied 1:1 from the performance-record snapshot). Service date by default; billing-run date for pricingDateBasis=BILLING_DATE.

Default: nullnullable

rateSourcestringoptional

ADR 0415 — provenance of the applied hourly rate (copied 1:1 from the performance-record snapshot). `record` = rate frozen at booking time with unknown origin (legacy).

Werte

contractparty_overrideparty_discountarticleservice_typerecordnull

Default: nullnullable

costTypeIdstringoptional

Cost type UUID (Kostenträger) for DATEV

PatternDefault: nullnullable

taxKeystringoptional

DATEV Steuerschlüssel (e.g. "9" for 19% USt., "8" for 7%)

max 10 ZeichenDefault: nullnullable

netAmountstringoptional

Net total (excl. VAT) as decimal string

Patternnullable

vatAmountstringoptional

VAT total as decimal string

Patternnullable

grossAmountstringoptional

Gross total (incl. VAT) as decimal string

Patternnullable

vatRatestringoptional

Default VAT rate for this invoice

Default: "19"

currencystringoptional

max 3 ZeichenDefault: "EUR"

paymentTermsDaysintegeroptional

Payment terms in days (e.g. 14, 30)

≥ 0nullable

pdfFileIduuidoptional

Reference to stored PDF file in files collection

nullable

weclappIdstringoptional

External weclapp sales invoice ID (if synced from weclapp)

read-onlynullable

weclappBaseUrlstringoptional

Base URL of the weclapp tenant (e.g. https://demo.weclapp.com) for deep-linking

read-onlynullable

externalVersionstringoptional

External system version (e.g. weclapp `version` field). Used to detect changes without re-downloading the PDF.

read-onlynullable

syncedAtdatetimeoptional

Timestamp of the last successful sync from the external system

read-onlynullable

customerPaymentReportedAtdatetimeoptional

Set when the customer pressed "Bezahlt gemeldet" in the portal. Does NOT change `status` — the MSP confirms separately. UI surfaces this as a yellow "Zahlung gemeldet" pill until the MSP transitions to PAID.

read-onlynullable

customerPaymentReportedByuuidoptional

Customer portal user who reported the payment

read-onlynullable

customerPaymentReferencestringoptional

Optional reference text from the customer (e.g. SEPA reference, IBAN-Last4)

max 200 Zeichenread-onlynullable

groupingModestringoptional

Grouping mode used when generating line items from performance record

Werte

onePositionperTicketperEntry

nullable

servicePeriodFromdateoptional

Service period start (from performance record)

nullable

servicePeriodTodateoptional

Service period end (from performance record)

nullable

salesOrderIdstringoptional

Source sales order UUID (if generated from order)

PatternDefault: nullnullable

proposalIdstringoptional

Source proposal UUID (if traceable to a proposal)

PatternDefault: nullnullable

Standard-Endpoints

Diese Resource folgt dem generischen CRUD-Vertrag der Plattform. Lesen Sie die Konventionen für Pagination, Idempotenz, Optimistic Locking und Audit. Die wichtigsten Endpoints:

GET /api/v1/invoices — Liste, paginiert + filterbar
GET /api/v1/invoices/<id> — Einzelne Entity
POST /api/v1/invoices — Anlegen
PATCH /api/v1/invoices/<id> — Teil-Update
DELETE /api/v1/invoices/<id> — Soft-Delete
GET /api/v1/invoices/<id>/timeline — Audit + Aktivitäten