Usage for EN16931 conforming ZUGFeRD files

[JohnHuynh]

Hi, I'm new to this topic and would like to know more about the general approach of converting normal PDFs to ZUGFeRD PDFs.

Since my application already has invoice PDF generation, I wanted to expand the generation by converting the existing PDFs to ZUGFeRD PDFs. Therefore, I use the ZUGFeRDExporterFromA3 to load the PDF-bytes and set and generate the xml separately by using the generateXML() function from the ZUGFeRD2PullProvider with the "EN16931" Profile and a corresponding Invoice object.

As I export the result, I get a valid pdf according to the validation of the ZUGFeRDValidator.

But I wonder if everything is correct with this approach, since I want to create invoices for leasing which is not a typical purchase maybe.

I ask this because I noticed a difference in a sample of the official ZUGFeRD examples and my generated Invoice by mustang:

In the example of the ferd-net.de site:

<ram:SpecifiedLineTradeAgreement>
        <ram:NetPriceProductTradePrice>
          <ram:ChargeAmount>86.5500</ram:ChargeAmount>
        </ram:NetPriceProductTradePrice>
      </ram:SpecifiedLineTradeAgreement>
      <ram:SpecifiedLineTradeDelivery>
        <ram:BilledQuantity unitCode="DAY">2.0000</ram:BilledQuantity>
      </ram:SpecifiedLineTradeDelivery>
      <ram:SpecifiedLineTradeSettlement>
        <ram:ApplicableTradeTax>
          <ram:TypeCode>VAT</ram:TypeCode>
          <ram:CategoryCode>S</ram:CategoryCode>
          <ram:RateApplicablePercent>19.00</ram:RateApplicablePercent>
        </ram:ApplicableTradeTax>
        <ram:SpecifiedTradeSettlementLineMonetarySummation>
          <ram:LineTotalAmount>173.10</ram:LineTotalAmount>
        </ram:SpecifiedTradeSettlementLineMonetarySummation>
</ram:SpecifiedLineTradeSettlement>

In my generated xml:

<ram:SpecifiedLineTradeAgreement>
       <ram:NetPriceProductTradePrice>
         <ram:ChargeAmount>1.0000</ram:ChargeAmount>
         <ram:BasisQuantity unitCode="DAY">1.0000</ram:BasisQuantity>
       </ram:NetPriceProductTradePrice>
     </ram:SpecifiedLineTradeAgreement>
     <ram:SpecifiedLineTradeDelivery>
       <ram:BilledQuantity unitCode="DAY">30.0000</ram:BilledQuantity>
     </ram:SpecifiedLineTradeDelivery>
     <ram:SpecifiedLineTradeSettlement>
       <ram:ApplicableTradeTax>
         <ram:TypeCode>VAT</ram:TypeCode>
         <ram:CategoryCode>S</ram:CategoryCode>
         <ram:RateApplicablePercent>19.00</ram:RateApplicablePercent>
       </ram:ApplicableTradeTax>
       <ram:SpecifiedTradeSettlementLineMonetarySummation>
         <ram:LineTotalAmount>100.00</ram:LineTotalAmount>
       </ram:SpecifiedTradeSettlementLineMonetarySummation>
     </ram:SpecifiedLineTradeSettlement>

The difference is that my version has an additional <ram:BasisQuantity unitCode="DAY">1.0000</ram:BasisQuantity> which seems odd to me. The generateXML() function always applies the same unitCode on BasisQuantity and BilledQuantity. Is that correct?

There is little documentation about how to go about things, so how should I proceed? Is this the right approach of converting already existing PDFs to ZUGFeRD invoices?

Also, how do I validate ZUGFeRD invoices with the "EN16931" profile? It seems that the ZUGFeRDValidator only validates for the profile "XRechnung"?

And how are other invoice types handled such as cancellations?

[jstaerk]

The generateXML() function always applies the same unitCode on BasisQuantity and BilledQuantity. Is that correct?
It's not uncorrect, it may thinkable to have a different case but so far nobody needed/implemented it

"DAY" is a correct unit code, for the other ones (like H87=piece) have a look at
the "Full listing of the code lists as used in EN16931 - version 14.0" from https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/Registry+of+supporting+artefacts+to+implement+EN16931

There is little documentation about how to go about things, so how should I proceed? Is this the right approach of converting already >existing PDFs to ZUGFeRD invoices?
PDF/A I hope, and it depends, what you want to do?
As for information: you can e.g. download the ZUGFeRD Infopaket https://www.ferd-net.de/standards/zugferd-2.3/zugferd-2.3.html , it comes with samples, the spec, scheme and schematron files and a reference, called technical appendix, TA for short.

Also, how do I validate ZUGFeRD invoices with the "EN16931" profile? It seems that the ZUGFeRDValidator only validates for the profile >"XRechnung"?
No it should do all other profiles. Actually here's a little architecture, for XRechnung it uses the schematrons from Kosit and for EN16931 the ones from CEN additional to the ZUGFeRD ones: https://raw.githubusercontent.com/ZUGFeRD/mustangproject/refs/heads/master/doc/ZUV-Architektur.svg

And how are other invoice types handled such as cancellations?
On a file level, they have different type codes, 380 is the standard invoice, 381 is a cancellation (I'm not sure if thats already supported by mustang), 384 is a corrected invoice (quantities usually being negative which leads to negative amounts) and 389 is credit note (again usually with positive amounts). Please note that the most important part of the EN16931 standard, EN16931-1 with requirements, business terms, calculation and rounding rules is available for free, in german e.g. from https://www.beuth.de/en/standard/din-en-16931-1/314992770 .

hope that helps
Jochen

[JohnHuynh]

Thank you for the answer.

PDF/A I hope, and it depends, what you want to do?
As for information: you can e.g. download the ZUGFeRD Infopaket https://www.ferd-net.de/standards/zugferd-2.3/zugferd-2.3.html , it comes with samples, the spec, scheme and schematron files and a reference, called technical appendix, TA for short.

So firstly, I created PDF files which are not PDF/A but I somehow managed to convert them to a ZUGFeRD file and attaching an xml via mustang which validates (with "XRechnung" errors, according to the validation text of ZUGFeRDValidator.validate()). Is that alarming not to use a PDF/A in that case? Here is some code:

ZUGFeRDExporterFromA3 ze = new ZUGFeRDExporterFromA3();
// pdfData is not PDF/A
ze.load(pdfData);
System.out.println("Attaching ZUGFeRD-Data");
ze.setXML(createMustangXmlData(invoice));
System.out.println("Writing ZUGFeRD-PDF");
var output = new ByteArrayOutputStream();
ze.export(output);

System.out.println("Validating ZUGFeRD-PDF");
ZUGFeRDValidator validator = new ZUGFeRDValidator();
String validationText = validator.validate(output.toByteArray(), "validation");

No it should do all other profiles. Actually here's a little architecture, for XRechnung it uses the schematrons from Kosit and for EN16931 the ones from CEN additional to the ZUGFeRD ones: https://raw.githubusercontent.com/ZUGFeRD/mustangproject/refs/heads/master/doc/ZUV-Architektur.svg

Does that mean that the validate() function of ZUGFeRDValidator validates against all schemas at once? And once there is an error for a profile it provides error information about it? Because I only got "XRechnung" Errors until now. I just want to know if every rule is met from the "EN16931" profile.

[jstaerk]

So firstly, I created PDF files which are not PDF/A but I somehow managed to convert them to a ZUGFeRD file and attaching an xml via >mustang which validates (with "XRechnung" errors, according to the validation text of ZUGFeRDValidator.validate()). Is that alarming not to >use a PDF/A in that case?

Yes, thats an issue, Factur/X/ZUGFeRD are specified for PDF/A-3 and -4 only and mustang does not provide a way to convert plain pdf to pdf/a, only pdf/a-1 to PDF/A-3.

Does that mean that the validate() function of ZUGFeRDValidator validates against all schemas at once? And once there is an error for a
profile it provides error information about it? Because I only got "XRechnung" Errors until now. I just want to know if every rule is met from
the "EN16931" profile.

Not all at once, it checks which ones are applicable and applies them subsequently. And we're not only talking about the Schema but in particular also about Schematron files. And the error type will let you know if the error is from the CEN schematrons or different, feel free to refer to the homepage for the list of possible error codes. And yes, the intention is that both checks are applied and I'm pretty confident that this works at least in CII but please confirm.

kind regards
Jochen

[JohnHuynh]

Yes, thats an issue, Factur/X/ZUGFeRD are specified for PDF/A-3 and -4 only and mustang does not provide a way to convert plain pdf to pdf/a, only pdf/a-1 to PDF/A-3.

1. Why does mustang convert my plain pdf file successfully though? And what problems could possibly occur?
2. So if I provide a PDF/A-3 file this should be fine? When creating a PDF/A-3 file, there are a few color profiles that you can choose from. I chose sRGB2014.icc from this site https://www.color.org/srgbprofiles.xalter. Do you perhaps any experience with this? What profile is used for ZUGFeRD?

Not all at once, it checks which ones are applicable and applies them subsequently. And we're not only talking about the Schema but in particular also about Schematron files. And the error type will let you know if the error is from the CEN schematrons or different, feel free to refer to the homepage for the list of possible error codes. And yes, the intention is that both checks are applied and I'm pretty confident that this works at least in CII but please confirm.

Ok, maybe I just have a valid pdf then that was conforming to "EN16931" but not "XRechnung".

Thank you anyways for the answers.