Finax Invoice Helper (Frontend)

The Finax Invoice Helper provides everything you need to build a valid Finax JSON payload inside a form. Every BrixxApi instance (app) exposes:

• the object app.finax

• identical wrapper methods directly on app (e.g. app.createFinaxInvoice, app.addFinaxLine)

Quick start

const invoice = app.createFinaxInvoice({
  invoiceNumber: "2024-001",
  issueDate: "2024-11-08",
  buyerReference: "PROJ-900",
  seller: { name: "Gebra IT GmbH" },
  buyer: { name: "Kunde AG" }
});

app.addFinaxLine(invoice, {
  id: "1",
  quantity: 1,
  unitCode: "H87",
  netAmount: 1000,
  vat: { code: "S", rate: 19 },
  item: { name: "Consulting" }
});

const payload = app.toFinaxPayload(invoice);

await app.businessFunction({
  functionName: "Finax",
  methodName: "CreateEInvoice",
  format: "xrechnung",
  cius: "XRechnung",
  invoice: payload,
  options: { returnXml: true }
});

API overview

Method	Purpose
createFinaxInvoice(options)	Creates the base structure and validates mandatory fields (invoiceNumber, issueDate, buyerReference, seller, buyer).
setFinaxSeller(invoice, seller) / setFinaxBuyer(...)	Updates seller/buyer master data (address, IDs, endpoints, contacts).
setFinaxPaymentTerms(invoice, terms)	Builds payment terms including the Finax discount macros (#SKONTO#TAGE=…).
setFinaxPaymentInstructions(invoice, instructions)	IBAN/BIC and payment method (payment_means_type_code).
setFinaxDocumentTotals(invoice, totals)	Stores totals (net/gross/VAT, discounts, rounding).
addFinaxVat(invoice, vat)	Adds entries to vat_breakdown.
addFinaxLine(invoice, line)	Adds invoice lines including price, VAT, and references.
addFinaxAllowance(invoice, allowance)	Header-level discounts or charges.
addFinaxNote(invoice, text, subjectCode)	Free-text notes.
setFinaxDelivery(invoice, delivery)	Delivery date/location/party.
toFinaxPayload(invoice)	Deep copy without prototype references – safe for API calls.

Every method returns the invoice so you can chain calls.

Detailed areas

Master data & identifiers

• seller/buyer accept identifiers either as a single object or an array.

• For electronic addresses (endpoint) pass both value and scheme.

• Example:

  app.setFinaxSeller(invoice, {
    name: "Gebra IT GmbH",
    vatId: "DE123456789",
    identifier: [{ scheme: "0094", value: "DE123456789" }],
    endpoint: { value: "9930:123456789", scheme: "9930" }
  });

Payment terms & instructions

• setFinaxPaymentTerms automatically builds the Finax macros:

  app.setFinaxPaymentTerms(invoice, {
    netDays: 30,
    skonto: [{ days: 10, percent: 2 }]
  });

• setFinaxPaymentInstructions supports multiple bank accounts (creditTransfer as array or single object).

Totals, VAT, and lines

• Call setFinaxDocumentTotals once all amounts are known. Unused fields get pruned automatically.

• addFinaxVat accepts taxableAmount, taxAmount, code, rate, plus optional exemptions.

• addFinaxLine covers quantity, unit, pricing, periods, references (order/contract), and per-line VAT.

Extending the document

• addFinaxAllowance separates discounts (isCharge: false) and surcharges (isCharge: true).

• addFinaxNote is great for internal hints or standardized messages (subjectCode: "INV").

• setFinaxDelivery covers date, location (name/address), and delivery party – important for goods shipments.

Best practices

• Only set what you need – the helper removes undefined fields to avoid validation issues.

• Dates are normalized – createFinaxInvoice already converts issueDate to ISO (YYYY-MM-DD).

• Always call toFinaxPayload so no proxies/getters leak into the HTTP request.

• Combine helper + wiki – use this file together with CreateEInvoice for the full story.

• CIUS awareness – the helper itself is CIUS agnostic; choose the variant when calling CreateEInvoice.

For more end-to-end scenarios check FinaxExamples.