Billing Documents

Billing documents are the output of cycle calculation. In core tSM billing they represent invoices and related accounting documents that can be printed and sent to the customer.

This document covers billing document structures, line composition, document typing/status, and SAP export payload support.

---

1. Business Meaning

1.1 What a Billing Document Represents

BillingDocument is the header-level accounting document for one customer and billing cycle. It stores invoice identifiers, due dates, totals, currency, and lifecycle status.

1.2 What a Billing Document Line Represents

BillingDocumentLine is the item-level charge row on the document. Lines carry quantity, VAT, unit/line price values, ordering (sortOrder), and optional links to catalog specification and runtime service configuration.

1.3 Document Type and Status Governance

• BillingDocumentType controls business type, accounting type, templates, and generation behavior.
• BillingDocumentStatus controls lifecycle states.
• BillingDocumentAccountingType enum marks key accounting semantics (INVOICE, CORRECTIVE_TAX).

This allows multiple document types in one installation (for example invoice, corrective tax document, custom settlement document).

1.4 SAP Export Document

SapDocument groups billing documents for SAP-oriented CSV integration and tracks export status.

---

2. Entity Reference: BillingDocument (BillingDocument)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Billing document primary key.
name	String	Yes	No	Human-readable document name.
key	String	Yes	No	Technical/business key (ASCII without spaces recommended).
status	String	Yes (business)	No	FK code of document status (BillingDocumentStatus.code).
billingCycle	String	Yes (business)	No	FK code of billing cycle (BillingCycle.code).
customerId	String	Yes (business)	No	FK identifier of CRM customer.
priceWithVat	Double	Yes	No	Document total amount.
invoiceNumber	String	No	No	Invoice number/identifier shown on customer document.
invoicedFor	String	No	No	Optional explanatory text for invoiced subject.
invoiceDate	Date	No	No	Invoice issue date.
dueDate	Date	No	No	Invoice maturity date.
billingCurrencyCode	String	Yes	No	FK code of currency (Currency.code).
dataTags	List<String>	No	No	Optional labels/tags.
billingDocumentType	String	Yes	No	FK code of document type (BillingDocumentType.code).
chars	TsmChars	No	No	Dynamic document attributes.
description	String	No	No	Optional description.
accountId	UUID	No	No	Optional account reference.

2.1 Practical Notes

• API schema flags several FK fields as required for normal billing flow (status, billingCycle, customerId).
• The field name is priceWithVat; treat it as authoritative for integrations and data mapping.

---

3. Entity Reference: BillingDocumentLine (BillingDocumentLine)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Line primary key.
name	String	Yes	No	Line display name.
billingDocumentCode	String	Yes	No	FK code of parent billing document.
chars	TsmChars	No	No	Dynamic line attributes.
quantity	Double	Yes (business)	No	Line quantity/amount multiplier.
priceWithoutVAT	Double	No	No	Price excluding VAT (defaults to 0.0).
vat	Double	Yes	No	VAT value (defaults to 0.0).
sortOrder	Int	Yes	No	Order used for invoice rendering.
entityCatalogSpecificationId	UUID	No	No	Optional linked catalog specification ID.
entityInstanceConfigurationId	UUID	No	No	Optional linked runtime configuration ID.
parentDocumentLineId	UUID	No	No	Optional parent line for hierarchical rendering.
data	Map<String, Any?>	No	No	Additional custom payload.

---

4. Entity Reference: BillingDocumentType (BillingDocumentType)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Document type primary key.
code	String	Yes	No	Technical type code.
name	String	Yes	No	Display name.
validityFrom	Date	No	No	Validity start.
validityTo	Date	No	No	Validity end.
description	String	No	No	Optional type description.
localizationData	LocalizationData	No	No	Localization payload.
billingDocumentSpecId	UUID	No	No	Optional billing document specification reference.
billingDocumentLineSpecId	UUID	No	No	Optional billing document line specification reference.
formatterDocumentTemplateId	UUID	No	No	Optional formatter template reference for output generation.
tsmModuleId	UUID	No	No	Optional module reference.
mnemonicCode	String	No	No	Optional mnemonic code.
aggregationTql	String	No	No	Optional aggregation TQL definition.
createPrivilege	String	No	No	Optional privilege required for create operations.
accountingType	BillingDocumentAccountingType	No	No	Accounting behavior marker (INVOICE or CORRECTIVE_TAX).
registry	Map<String, Any?>	No	No	Registry payload.
config	Map<String, Any?>	No	No	Additional configuration payload.
dataTags	List<String>	No	No	Optional labels/tags.
tsmModule	String	No	No	Optional module code reference.
icon	String	No	No	Optional icon metadata.
sapConfig	String	No	No	Optional SAP integration configuration payload.

---

5. Entity Reference: BillingDocumentStatus (BillingDocumentStatus)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Status primary key.
code	String	Yes	No	Technical status code.
name	String	Yes	No	Display name.
validityFrom	Date	No	No	Validity start.
validityTo	Date	No	No	Validity end.
description	String	No	No	Optional status description.
localizationData	LocalizationData	No	No	Localization payload.
dataTags	List<String>	No	No	Optional labels/tags.
config	Map<String, Any?>	No	No	Additional configuration payload.

---

6. Entity Reference: SapDocument (SapDocument)

Field	Type	Required	Read-only	Description
id	UUID	No	No	SAP export document primary key.
status	String	Yes (business)	No	SAP document status code.
billingCycle	String	Yes (business)	No	Billing cycle code used for export batching.
customerId	String	Yes (business)	No	Customer identifier in export context.
hasCsv	Boolean	No	No	Indicates whether CSV export payload was generated.
billingDocumentIds	List<UUID>	Yes	No	Billing documents included in this SAP export package.

---

7. Enum Reference: BillingDocumentAccountingType (BillingDocumentAccountingType)

Value	Meaning
INVOICE	Standard invoice accounting type.
CORRECTIVE_TAX	Corrective tax document accounting type.