CreateEInvoice

This article describes the GEBRA Suite endpoint methodName: "CreateEInvoice" and covers all relevant fields, workflows, and best practices.

Goal of the endpoint

• Generate a compliant e-invoice XML plus a PDF (standard layout or ZUGFeRD hybrid).

• Optionally store the results as attachments and link them to apps/records.

• Return status messages and, if requested, the raw XML.

Request fields

Field	Required	Description
format	yes	"xrechnung" (UBL) or "zugferd" (CII). Determines whether a ZUGFeRD hybrid is produced.
cius	no	Only relevant for format: "xrechnung". Accepts XRechnung (default) or PEPPOL BIS Billing 3.0 and sets the X-Finax-Cius header.
invoice	yes	JSON payload following the Finax schema – easiest to build via the Finax Invoice Helper.
fileName	no	Base name for attachments/post processing (default: "Invoice").
options.returnXml	no	Returns the generated XML in the response.
options.pdfAttachmentId	no	Re-uses an existing PDF attachment.
archive.enabled	no	Stores PDF/XML in the archive and links them to appName + recordId.
archive.appName / archive.recordId	required when archive enabled	Target app and record ID.
archive.documentTypeId	optional	Document type for the saved attachments.

Backend workflow

1. Validation

   • Checks required fields and CIUS. Invalid combinations return 400 with a useful message.

2. XML generation

   • xrechnung: calls /v1/xml/ubl/ and adds X-Finax-Cius if needed.

   • zugferd: calls /v1/xml/cii/.

3. PDF handling

   • Reuses existing PDF attachments when provided.

   • Otherwise posts to /v1/pdf/json/ to create the standard PDF.

   • For ZUGFeRD without a PDF the controller merges the generated PDF + XML via /v1/pdf/merge/.

4. Archiving (optional)

   • Saves PDF/XML through SaveAttachmentAsync and links them to the target record.

5. Response + journaling

   • Returns attachment IDs, XML, and messages.

   • FinaxJournal records path, duration, FinaxExternalRequestId, etc.

Response fields

Field	Description
Messages	Steps performed (e.g. “Generated PDF via Finax.”).
Xml	Present only when options.returnXml is true.
XmlFormat	"UBL" or "CII" matching the generated XML.
PdfAttachmentId	ID of the stored/reused PDF.
XmlAttachmentId	ID of the stored XML (archiving only).
BrixxPostProcessing	Contains the Base64 PDF when returnPdf is enabled in the business function call.

Example: XRechnung with archiving

const invoice = app.createFinaxInvoice({
  invoiceNumber: "2024-INV-007",
  issueDate: "2024-11-08",
  buyerReference: "BEHOERDE-99",
  seller: { name: "Gebra IT GmbH" },
  buyer: { name: "Bauamt Musterstadt" }
});
app.addFinaxLine(invoice, { id: "1", quantity: 1, unitCode: "H87", netAmount: 1500 });

const response = await app.businessFunction({
  functionName: "Finax",
  methodName: "CreateEInvoice",
  format: "xrechnung",
  cius: "PEPPOL BIS Billing 3.0",
  invoice,
  fileName: "2024-INV-007",
  options: { returnXml: true },
  archive: {
    enabled: true,
    appName: "FinanceApp",
    recordId: 4711,
    documentTypeId: 987
  }
});

console.log(response.Xml);             // Inspect XML
console.log(response.PdfAttachmentId); // Stored PDF ID

Example: ZUGFeRD hybrid without archiving

const invoice = app.createFinaxInvoice({ /* required fields */ });
app.addFinaxLine(invoice, { id: "1", quantity: 8, unitCode: "C62", netAmount: 499.9 });

await app.businessFunction({
  functionName: "Finax",
  methodName: "CreateEInvoice",
  format: "zugferd",
  invoice,
  options: {
    returnXml: false,   // XML is still generated for the hybrid
    pdfAttachmentId: null
  }
});
// Result: PDF with embedded XML returned via PostProcessing or attachment

Tips & pitfalls

• Enabling archive without appName/recordId results in a hard error – validate upfront.

• For zugferd without pdfAttachmentId, Finax must generate a PDF first and then merge it. Expect a slightly longer runtime.

• options.returnXml is independent of archiving. You can receive the XML in the response and store it as an attachment at the same time.

• Error texts from Finax are passed straight through in messages and in the journal – perfect for support investigations.

• Only set cius when a recipient explicitly requires PEPPOL; otherwise keep the default.

More end-to-end scenarios are available in FinaxExamples.