E-Invoice

This page summarizes how our consultants use the Finax integration inside the GEBRA Suite. Detailed explanations live in the companion articles:

• CreateEInvoice

• ReadEInvoice

• Finax Invoice Helper

• Practical examples

Key features

• Create XRechnung, PEPPOL, and ZUGFeRD documents.

• Automatic journaling including FinaxExternalRequestId for traceability.

• Built-in archive integration links generated PDF/XML files to apps and records.

• The frontend helper (app.finax) reduces manual JSON shaping.

Supported GEBRA endpoints

methodName	Purpose	Key inputs	Main output
CreateEInvoice	Generates XML + PDF (XRechnung, PEPPOL BIS Billing 3.0, ZUGFeRD) and optionally saves attachments.	format, cius, invoice, options, archive	PostProcessing (PDF), attachment IDs, XML
ReadEInvoice	Reads incoming PDF/XML (incl. ZUGFeRD hybrid) and returns the Finax JSON.	attachmentId or xmlAttachmentId or xml, returnXml	invoice JSON, optional XML, messages

High-level flow

1. Business function – app.businessFunction({ functionName: "Finax", methodName: ... }).

2. Controller logic

   • Validates required fields and CIUS.

   • Calls Finax endpoints (/v1/xml/ubl, /v1/xml/cii, /v1/pdf/json, /v1/pdf/merge, /v1/pdf/xml, /v1/json/xml).

   • Persists attachments and journal entries.

3. Response – Attachment IDs, generated XML, PDF payloads, or plain status messages.

Prerequisites

• Archiving (archive.enabled) requires both appName and recordId.

• For format: "xrechnung" you may set cius ("XRechnung" or "PEPPOL BIS Billing 3.0"). Default is XRechnung.

• For ZUGFeRD either provide an existing PDF or let the system generate & merge one automatically.

Quick start

1. Build the invoice

   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, netAmount: 1000, unitCode: "H87" });

2. Trigger CreateEInvoice

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

3. Use the result

   • Display or link response.Xml.

   • Store response.PdfAttachmentId/XmlAttachmentId.

   • Log response.Messages.

FAQs

• Where do I see errors? In the response (error) and in the invoice journal (Configuration → Admin tools → invoice journal).

• Do I always have to set cius? No. Without a value the controller uses XRechnung. Only set it when the recipient requires PEPPOL.

• Can I attach multiple files? A single call creates at most one PDF and one XML attachment. Link additional files afterwards if needed.

Each linked article digs deeper into its topic and provides more examples and pitfalls.