ReadEInvoice

methodName: "ReadEInvoice" converts incoming e-invoices (PDF or XML) into the Finax JSON representation. This article explains the inputs, backend behavior, and practical examples.

Use cases

• A ZUGFeRD or XRechnung PDF is uploaded into the suite and needs to be converted into structured data.

• Existing XML files should be turned into Finax JSON for further processing.

• Validate incoming invoices (status messages + business summary).

Request fields

Field	Required	Description
attachmentId	alternative to xmlAttachmentId/xml	ID of an existing attachment (PDF or XML).
xmlAttachmentId	alternative to attachmentId/xml	Direct reference to an XML attachment in the archive.
xml	alternative to the IDs	Raw XML string (e.g. from a form field).
returnXml	no	Returns the parsed XML in the response.
credentials	no	Optional API key in case it is not configured globally.

Important: set exactly one data source (attachmentId XOR xmlAttachmentId XOR xml). Otherwise the endpoint returns 400.

Backend workflow

1. Determine the source

   • For PDF attachments the controller first checks that it is a binary PDF.

2. Optional XML extraction

   • PDF → /v1/pdf/xml/ to extract the embedded XML.

   • XML string/attachment → used directly.

3. Convert to JSON

   • /v1/json/xml returns the Finax JSON plus metadata.

4. Build the response

   • JSON ends up in response.Invoice.

   • response.Xml is only populated when returnXml is true.

5. Journaling

   • FinaxJournal stores success/failure, attachment IDs, and a businessSummary.

Response fields

Field	Description
Invoice	Finax JSON object with all extracted data.
Xml	Original or extracted XML (optional).
Messages	Notes from Finax (format detection, validation hints, etc.).

Example: read a PDF attachment

const result = await app.businessFunction({
  functionName: "Finax",
  methodName: "ReadEInvoice",
  attachmentId: 8123,
  returnXml: true
});

console.log(result.Invoice?.document_totals);
app.setFieldValue("txtXmlPreview", result.Xml);

Example: XML from a form field

const xml = app.getFieldValue("txtIncomingXml");

const result = await app.businessFunction({
  functionName: "Finax",
  methodName: "ReadEInvoice",
  xml,
  returnXml: false
});

await app.setJsonValue("jsonInvoice", result.Invoice);

Tips & troubleshooting

• With returnXml: true you can save or display the XML regardless of the original medium.

• If the PDF is broken or contains no embedded XML, Finax returns an error (“No embedded XML found”, etc.) that surfaces both in the response and the journal.

• ProcessReadEInvoiceAsync automatically tries to resolve the related app/record from the attachment so journal entries show up on the correct dataset.

• For large PDFs check whether an XML version is already stored in the archive and prefer xmlAttachmentId when possible.