search

horstoeko / zugferd

ZUGFeRD/XRechnung/Factur-X Library
MIT License
214 stars 34 forks source link

[FEATURE] Add bank name to addDocumentPaymentMeanToCreditTransfer()? #52

Closed danielmarschall closed 6 months ago

danielmarschall commented 6 months ago

(SEPA) Direct Debit (Lastschrift)

Currently, the following information can be entered to addDocumentPaymentMeanToDirectDebit:

$document->addDocumentPaymentMeanToDirectDebit($kunde['BankIBAN']);

The ZUGFeRD 1.0 documentation gives the following example:

        <ram:SpecifiedTradeSettlementPaymentMeans>
            <ram:TypeCode>59</ram:TypeCode>
            <ram:Information>Betrag wird per SEPA-Lastschrift eingezogen</ram:Information>
            <ram:ID schemeAgencyID="DE98ZZZ09999999999">REF A-123</ram:ID>
            <ram:PayerPartyDebtorFinancialAccount>
                <ram:IBANID>DE21860000000086001055</ram:IBANID>
                <ram:AccountName>Bundeskasse Halle -Darlehen-</ram:AccountName>
            </ram:PayerPartyDebtorFinancialAccount>
            <ram:PayerSpecifiedDebtorFinancialInstitution>
                <ram:BICID>MARKDEF1860</ram:BICID>
                <ram:Name>Deutsche Bundesbank -Filiale Leipzig-</ram:Name>
            </ram:PayerSpecifiedDebtorFinancialInstitution>
        </ram:SpecifiedTradeSettlementPaymentMeans>

I miss a lot of information here, which might be good to include in the XRechnung, like the Lastschriftmandat (REF A-123) and the Gläuber-ID (DE98ZZZ09999999999). What do you think?

(SEPA) Credit Transfer (Überweisung)

Currently, the following information can be entered to addDocumentPaymentMeanToDirectDebit:

$document->addDocumentPaymentMeanToCreditTransfer($lieferant['BankIBAN'], $lieferant['BankKontoinhaber'], null/*Kontonummer*/, $lieferant['BankBIC']);

The ZUGFeRD 1.0 documentation gives the following example:

        <ram:SpecifiedTradeSettlementPaymentMeans>
            <ram:TypeCode>31</ram:TypeCode>
            <ram:Information>per Überweisung</ram:Information>
            <ram:PayeePartyCreditorFinancialAccount>
                <ram:IBANID>DE21860000000086001055</ram:IBANID>
                <ram:AccountName>Bundeskasse Halle -Darlehen-</ram:AccountName>
            </ram:PayeePartyCreditorFinancialAccount>
            <ram:PayeeSpecifiedCreditorFinancialInstitution>
                <ram:BICID>MARKDEF1860</ram:BICID>
                <ram:Name>Deutsche Bundesbank -Filiale Leipzig-</ram:Name>
            </ram:PayeeSpecifiedCreditorFinancialInstitution>
        </ram:SpecifiedTradeSettlementPaymentMeans>

Also here, some information like the bank name are missing.

I would love helping with extending the code, but first I want to hear your opinion. Unfortunately, I am not sure if I can help, because I am not yet familiar with the inner workings of the framework

horstoeko commented 6 months ago

ZUGFeRD 1.0 is literally older than coal :-). Version 2.2 is currently in use. This has (sometimes “unfortunately”) too little information. The bank name is one of these missing pieces of information. You can download the current documentation at https://www.ferd-net.de/standards/zugferd-2.2/zugferd-2.2.html. You will see that there are currently no plans to implement your wishes in a compliant and valid manner.

Best regards....

danielmarschall commented 6 months ago

Actually, I am at bit confused.

I found this document "Das ZUGFeRD Format 1.0" (25.06.2024) with 131 pages and a lot of examples. Perfectly written and understandable...

The current Schnittstellenbeschreibung 2.1.1 contains a "Specification" document with 25 pages and a "TA" document which is 121 pages of pure mess... without examples, just a giant XML tree graphic. image

Did I miss something or did the specification really became that worse?

I didn't understand your reply correctly. Are the two 1.0 code examples I posted above, aren't they valid in 2.2 anymore?

horstoeko commented 6 months ago

Actually, I am at bit confused.

I can understand that. There is the ZUGFeRD community, but in my opinion there are no other transparent sources.

I found this document "Das ZUGFeRD Format 1.0" (25.06.2024) with 131 pages and a lot of examples. Perfectly written and understandable...

Where did you find that? Can you send me a URL? If that is indeed what was written, then it is absolutely wrong.

The current Schnittstellenbeschreibung 2.1.1 contains a "Specification" document with 25 pages and a "TA" document which is 121 pages of pure mess... without examples, just a giant XML tree graphic.

It's still like this.... Even in version 2.2, but there are plenty of examples - at least 10 for each profile

Did I miss something or did the specification really became that worse?

I don't think so, I just wouldn't rely on questionable sources in this regard. Please be sure to use the pages of the ZUGFeRD community as a reliable partner...

I didn't understand your reply correctly. Are the two 1.0 code examples I posted above, aren't they valid in 2.2 anymore?

I can answer that without a doubt - absolutely not. Any official validator would acknowledge this with an error.

Best regards...

danielmarschall commented 6 months ago

That's strange!

The document is here: https://konik.io/ZUGFeRD-Spezifikation/Das-ZUGFeRD-Format_1p0.pdf

I think "konik.io" is some kind of official source, if I understand correctly.

The Direct Debit (Lastschrift) example is at PDF page 70 (printed page number 69)

The Credit Transfer (Überweisung) example is taken from PDF page 85 (printed page number 84)

Actually, I haven't tried to manually include these examples in an XML and send it through a validator. (I will do that this afternoon.)

From a "gut feeling", the examples do look logical to me. After all, when you do a credit transfer by hand, you always need to know the name of the bank, so why shouldn't it be in the ZUGFeRD too? Especially, since not every bank has a BIC.

horstoeko commented 6 months ago

Hi @danielmarschall,

I am sending you an excerpt from the ZUGFeRD community page. As you can see, ZUGFeRD 1.0 is no longer the latest...

grafik (Source: https://www.ferd-net.de/standards/zugferd-versionsarchiv/zugferd-versionen.html?changelang=3

Unfortunately, I don't know how I can help you at the moment....

Best regards...

danielmarschall commented 6 months ago

Thank you very much for the help and clarification!

Indeed, example 1 (Direct Debit) does not validate with a modern validator. So, I guess this is a backward-compatibility breaking change in version 2.x. It's okay for me, since I do want to implement the latest ZUGFeRD version 2.2.1 -- I was just so attached to this 1.0 document because it is so nice and user-friendly written :-)

So, nothing needs to be done in regarding Direct Debit.

val-sch.1.1 CII-SR-443  warning [CII-SR-443] - ID should not be present
Pfad: /rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction[1]/ram:ApplicableHeaderTradeSettlement[1]
val-sch.1.2 CII-SR-382  warning [CII-SR-382] - AccountName should not be present
Pfad: /rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction[1]/ram:ApplicableHeaderTradeSettlement[1]
val-sch.1.3 CII-SR-385  warning [CII-SR-385] - Name should not be present
Pfad: /rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction[1]/ram:ApplicableHeaderTradeSettlement[1]
val-sch.2.1 PEPPOL-EN16931-R061 warning Mandate reference MUST be provided for direct debit.
Pfad: /rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction[1]/ram:ApplicableHeaderTradeSettlement[1]/ram:SpecifiedTradeSettlementPaymentMeans[1]
val-sch.2.2 BR-DE-30    error   [BR-DE-30] Wenn "DIRECT DEBIT" BG-19 vorhanden ist, dann muss "Bank assigned creditor identifier" BT-90 übermittelt werden.
Pfad: /rsm:CrossIndustryInvoice
val-sch.2.3 BR-DE-31    error   [BR-DE-31] Wenn "DIRECT DEBIT" BG-19 vorhanden ist, dann muss "Debited account identifier" BT-91 übermittelt werden.
Pfad: /rsm:CrossIndustryInvoice

The Credit Transfer example, however, does validate.

So, my suggestion (for this issue #52) would be to add the bank name to addDocumentPaymentMeanToCreditTransfer() - would that be possible?

        <ram:PayeeSpecifiedCreditorFinancialInstitution>
            <ram:BICID>MARKDEF1860</ram:BICID>
            <ram:Name>Deutsche Bundesbank -Filiale Leipzig-</ram:Name>
        </ram:PayeeSpecifiedCreditorFinancialInstitution>

(Edit: Fixed typo, Of course I meant addDocumentPaymentMeanToCreditTransfer , not addDocumentPaymentMeanToDirectDebit)

horstoeko commented 6 months ago

Hi @danielmarschall,

I've been thinking about this again. The problem is that I need to extend my XML serialization with a “field” that is not in any official documentation. The disadvantage of this is that you would have to actively inform all parties who receive such a customized XML that there is a small extension. Otherwise, they would deliberately ignore this additional information. I don't think this is practicable. The option you would have would be to derive the classes ZugferdDocumentBuilder and ZugferdDocumentReader in separate classes and to process or read the XML accordingly after the actual serialization/deserialization. However, I do not want to implement your requirement directly in the library, as it basically violates the official documentation.