1 package SL::DB::Helper::ZUGFeRD;
6 use parent qw(Exporter);
7 our @EXPORT = qw(create_zugferd_data create_zugferd_xmp_data);
9 use SL::DB::GenericTranslation;
12 use SL::Helper::ISO3166;
13 use SL::Helper::ISO4217;
14 use SL::Helper::UNECERecommendation20;
17 use Encode qw(encode);
18 use List::MoreUtils qw(any pairwise);
19 use List::Util qw(first sum);
23 my @line_names = qw(LineOne LineTwo LineThree);
27 return encode('UTF-8', $value // '');
32 return $::form->round_amount($value, 2);
37 my $type = $self->invoice_type;
40 return $type eq 'ar_transaction' ? $::locale->text('Invoice') : $self->displayable_type;
45 my $type = $self->invoice_type;
47 # 326 (Partial invoice)
48 # 380 (Commercial invoice)
49 # 384 (Corrected Invoice)
51 # 389 (Credit note, self billed invoice)
53 return $type eq 'credit_note' ? 381
54 : $type eq 'invoice_storno' ? 457
55 : $type eq 'credit_note_storno' ? 458
62 # Mapping from kivitendo's units to UN/ECE Recommendation 20 & 21.
63 my $code = SL::Helper::UNECERecommendation20::map_name_to_code($unit);
64 return $code if $code;
66 $::lxdebug->message(LXDebug::WARN(), "ZUGFeRD unit name mapping: no UN/ECE Recommendation 20/21 unit known for kivitendo unit '$unit'; using 'C62'");
71 sub _parse_our_address {
73 my @street = grep { $_ } ($::instance_conf->get_address_street1, $::instance_conf->get_address_street2);
75 push @result, [ 'PostcodeCode', $::instance_conf->get_address_zipcode ] if $::instance_conf->get_address_zipcode;
76 push @result, grep { $_->[1] } pairwise { [ $a, $b] } @line_names, @street;
77 push @result, [ 'CityName', $::instance_conf->get_address_city ] if $::instance_conf->get_address_city;
78 push @result, [ 'CountryID', SL::Helper::ISO3166::map_name_to_alpha_2_code($::instance_conf->get_address_country) // 'DE' ];
83 sub _customer_postal_trade_address {
86 # <ram:PostalTradeAddress>
87 $params{xml}->startTag("ram:PostalTradeAddress");
89 my @parts = grep { $_ } map { $params{customer}->$_ } qw(department_1 department_2 street);
91 $params{xml}->dataElement("ram:PostcodeCode", _u8($params{customer}->zipcode));
92 $params{xml}->dataElement("ram:" . $_->[0], _u8($_->[1])) for grep { $_->[1] } pairwise { [ $a, $b] } @line_names, @parts;
93 $params{xml}->dataElement("ram:CityName", _u8($params{customer}->city));
94 $params{xml}->dataElement("ram:CountryID", _u8(SL::Helper::ISO3166::map_name_to_alpha_2_code($params{customer}->country) // 'DE'));
96 # </ram:PostalTradeAddress>
99 sub _tax_rate_and_code {
100 my ($taxzone, $tax) = @_;
102 my ($tax_rate, $tax_code) = @_;
104 if ($taxzone->description =~ m{Au.*erhalb}) {
108 } elsif ($taxzone->description =~ m{EU mit}) {
113 $tax_rate = $tax->rate * 100;
114 $tax_code = !$tax_rate ? 'Z' : 'S';
117 return (rate => $tax_rate, code => $tax_code);
121 my ($self, %params) = @_;
123 my $item_ptc = $params{ptc_data}->{items}->[$params{line_number}];
125 my $taxkey = $item_ptc->{taxkey_id} ? SL::DB::TaxKey->load_cached($item_ptc->{taxkey_id}) : undef;
126 my $tax = $item_ptc->{taxkey_id} ? SL::DB::Tax->load_cached($taxkey->tax_id) : undef;
127 my %tax_info = _tax_rate_and_code($self->taxzone, $tax);
129 # <ram:IncludedSupplyChainTradeLineItem>
130 $params{xml}->startTag("ram:IncludedSupplyChainTradeLineItem");
132 # <ram:AssociatedDocumentLineDocument>
133 $params{xml}->startTag("ram:AssociatedDocumentLineDocument");
134 $params{xml}->dataElement("ram:LineID", $params{line_number} + 1);
135 $params{xml}->endTag;
137 $params{xml}->startTag("ram:SpecifiedTradeProduct");
138 $params{xml}->dataElement("ram:SellerAssignedID", _u8($params{item}->part->partnumber));
139 $params{xml}->dataElement("ram:Name", _u8($params{item}->description));
140 $params{xml}->endTag;
142 $params{xml}->startTag("ram:SpecifiedLineTradeAgreement");
143 $params{xml}->startTag("ram:NetPriceProductTradePrice");
144 $params{xml}->dataElement("ram:ChargeAmount", _r2($item_ptc->{sellprice}));
145 $params{xml}->endTag;
146 $params{xml}->endTag;
147 # </ram:SpecifiedLineTradeAgreement>
149 # <ram:SpecifiedLineTradeDelivery>
150 $params{xml}->startTag("ram:SpecifiedLineTradeDelivery");
151 $params{xml}->dataElement("ram:BilledQuantity", $params{item}->qty, "unitCode" => _unit_code($params{item}->unit));
152 $params{xml}->endTag;
153 # </ram:SpecifiedLineTradeDelivery>
155 # <ram:SpecifiedLineTradeSettlement>
156 $params{xml}->startTag("ram:SpecifiedLineTradeSettlement");
158 # <ram:ApplicableTradeTax>
159 $params{xml}->startTag("ram:ApplicableTradeTax");
160 $params{xml}->dataElement("ram:TypeCode", "VAT");
161 $params{xml}->dataElement("ram:CategoryCode", $tax_info{code});
162 $params{xml}->dataElement("ram:RateApplicablePercent", _r2($tax_info{rate}));
163 $params{xml}->endTag;
164 # </ram:ApplicableTradeTax>
166 # <ram:SpecifiedTradeSettlementLineMonetarySummation>
167 $params{xml}->startTag("ram:SpecifiedTradeSettlementLineMonetarySummation");
168 $params{xml}->dataElement("ram:LineTotalAmount", _r2($item_ptc->{linetotal}));
169 $params{xml}->endTag;
170 # </ram:SpecifiedTradeSettlementLineMonetarySummation>
172 $params{xml}->endTag;
173 # </ram:SpecifiedLineTradeSettlement>
175 $params{xml}->endTag;
176 # <ram:IncludedSupplyChainTradeLineItem>
180 my ($self, %params) = @_;
184 foreach my $item (@{ $params{ptc_data}->{items} }) {
185 $taxkey_info{$item->{taxkey_id}} //= {
189 my $info = $taxkey_info{$item->{taxkey_id}};
190 $info->{taxkey} //= SL::DB::TaxKey->load_cached($item->{taxkey_id});
191 $info->{tax} //= SL::DB::Tax->load_cached($info->{taxkey}->tax_id);
192 $info->{linetotal} += $item->{linetotal};
193 $info->{tax_amount} += $item->{tax_amount};
196 foreach my $taxkey_id (sort keys %taxkey_info) {
197 my $info = $taxkey_info{$taxkey_id};
198 my %tax_info = _tax_rate_and_code($self->taxzone, $info->{tax});
200 # <ram:ApplicableTradeTax>
201 $params{xml}->startTag("ram:ApplicableTradeTax");
202 $params{xml}->dataElement("ram:CalculatedAmount", _r2($params{ptc_data}->{taxes}->{$info->{tax}->{chart_id}}));
203 $params{xml}->dataElement("ram:TypeCode", "VAT");
204 $params{xml}->dataElement("ram:BasisAmount", _r2($info->{linetotal}));
205 $params{xml}->dataElement("ram:CategoryCode", $tax_info{code});
206 $params{xml}->dataElement("ram:RateApplicablePercent", _r2($tax_info{rate}));
207 $params{xml}->endTag;
208 # </ram:ApplicableTradeTax>
212 sub _format_payment_terms_description {
215 my (%vars, %amounts, %formatted_amounts);
217 local $::myconfig{numberformat} = $::myconfig{numberformat};
218 local $::myconfig{dateformat} = $::myconfig{dateformat};
220 if ($self->language_id) {
221 my $language = SL::DB::Language->load_cached($self->language_id);
222 $::myconfig{dateformat} = $language->output_dateformat if $language->output_dateformat;
223 $::myconfig{numberformat} = $language->output_numberformat if $language->output_numberformat;
226 $vars{currency} = $self->currency->name if $self->currency;
227 $vars{$_} = $self->customer->$_ for qw(account_number bank bank_code bic iban mandate_date_of_signature mandator_id);
228 $vars{$_} = $self->payment_terms->$_ for qw(terms_netto terms_skonto percent_skonto);
229 $vars{payment_description} = $self->payment_terms->description;
230 $vars{netto_date} = $self->payment_terms->calc_date(reference_date => $self->transdate, due_date => $self->duedate, terms => 'net')->to_kivitendo;
231 $vars{skonto_date} = $self->payment_terms->calc_date(reference_date => $self->transdate, due_date => $self->duedate, terms => 'discount')->to_kivitendo;
233 $amounts{invtotal} = $self->amount;
234 $amounts{total} = $self->amount - $self->paid;
236 $amounts{skonto_in_percent} = 100.0 * $vars{percent_skonto};
237 $amounts{skonto_amount} = $amounts{invtotal} * $vars{percent_skonto};
238 $amounts{invtotal_wo_skonto} = $amounts{invtotal} * (1 - $vars{percent_skonto});
239 $amounts{total_wo_skonto} = $amounts{total} * (1 - $vars{percent_skonto});
241 foreach (keys %amounts) {
242 $amounts{$_} = $::form->round_amount($amounts{$_}, 2);
243 $formatted_amounts{$_} = $::form->format_amount(\%::myconfig, $amounts{$_}, 2);
246 my $description = ($self->payment_terms->translated_attribute('description_long_invoice', $self->language_id) // '') || $self->payment_terms->description_long_invoice;
247 $description =~ s{<\%$_\%>}{ $vars{$_} }ge for keys %vars;
248 $description =~ s{<\%$_\%>}{ $formatted_amounts{$_} }ge for keys %formatted_amounts;
254 my ($self, %params) = @_;
256 return unless $self->payment_terms;
258 # <ram:SpecifiedTradePaymentTerms>
259 $params{xml}->startTag("ram:SpecifiedTradePaymentTerms");
261 $params{xml}->dataElement("ram:Description", _u8(_format_payment_terms_description($self)));
263 # <ram:DueDateDateTime>
264 $params{xml}->startTag("ram:DueDateDateTime");
265 $params{xml}->dataElement("udt:DateTimeString", $self->duedate->strftime('%Y%m%d'), "format" => "102");
266 $params{xml}->endTag;
267 # </ram:DueDateDateTime>
269 if ($self->payment_terms->percent_skonto && $self->payment_terms->terms_skonto) {
270 # <ram:ApplicableTradePaymentDiscountTerms>
271 $params{xml}->startTag("ram:ApplicableTradePaymentDiscountTerms");
272 $params{xml}->dataElement("ram:BasisPeriodMeasure", $self->payment_terms->terms_skonto, "unitCode" => "DAY");
273 $params{xml}->dataElement("ram:CalculationPercent", _r2($self->payment_terms->percent_skonto * 100));
274 $params{xml}->endTag;
275 # </ram:ApplicableTradePaymentDiscountTerms>
278 $params{xml}->endTag;
279 # </ram:SpecifiedTradePaymentTerms>
283 my ($self, %params) = @_;
285 # <ram:SpecifiedTradeSettlementHeaderMonetarySummation>
286 $params{xml}->startTag("ram:SpecifiedTradeSettlementHeaderMonetarySummation");
288 $params{xml}->dataElement("ram:LineTotalAmount", _r2($self->netamount));
289 $params{xml}->dataElement("ram:TaxBasisTotalAmount", _r2($self->netamount));
290 $params{xml}->dataElement("ram:TaxTotalAmount", _r2(sum(values %{ $params{ptc_data}->{taxes} })), "currencyID" => "EUR");
291 $params{xml}->dataElement("ram:GrandTotalAmount", _r2($self->amount));
292 $params{xml}->dataElement("ram:TotalPrepaidAmount", _r2($self->paid));
293 $params{xml}->dataElement("ram:DuePayableAmount", _r2($self->amount - $self->paid));
295 $params{xml}->endTag;
296 # </ram:SpecifiedTradeSettlementHeaderMonetarySummation>
299 sub _exchanged_document_context {
300 my ($self, %params) = @_;
302 # <rsm:ExchangedDocumentContext>
303 $params{xml}->startTag("rsm:ExchangedDocumentContext");
305 if ($::instance_conf->get_create_zugferd_invoices == 2) {
306 $params{xml}->startTag("ram:TestIndicator");
307 $params{xml}->dataElement("udt:Indicator", "true");
308 $params{xml}->endTag;
311 $params{xml}->startTag("ram:GuidelineSpecifiedDocumentContextParameter");
312 $params{xml}->dataElement("ram:ID", "urn:cen.eu:en16931:2017#conformant#urn:zugferd.de:2p0:extended");
313 $params{xml}->endTag;
314 $params{xml}->endTag;
315 # </rsm:ExchangedDocumentContext>
319 my ($self, %params) = @_;
321 $params{xml}->startTag("ram:IncludedNote");
322 $params{xml}->dataElement("ram:Content", _u8($params{note}));
323 $params{xml}->endTag;
326 sub _exchanged_document {
327 my ($self, %params) = @_;
329 # <rsm:ExchangedDocument>
330 $params{xml}->startTag("rsm:ExchangedDocument");
332 $params{xml}->dataElement("ram:ID", _u8($self->invnumber));
333 $params{xml}->dataElement("ram:Name", _u8(_type_name($self)));
334 $params{xml}->dataElement("ram:TypeCode", _u8(_type_code($self)));
336 # <ram:IssueDateTime>
337 $params{xml}->startTag("ram:IssueDateTime");
338 $params{xml}->dataElement("udt:DateTimeString", $self->transdate->strftime('%Y%m%d'), "format" => "102");
339 $params{xml}->endTag;
340 # </ram:IssueDateTime>
342 if ($self->language && (($self->language->template_code // '') =~ m{^(de|en)}i)) {
343 $params{xml}->dataElement("ram:LanguageID", uc($1));
346 my $std_notes = SL::DB::Manager::GenericTranslation->get_all(
348 translation_type => 'ZUGFeRD/notes',
350 language_id => undef,
351 language_id => $self->language_id,
353 '!translation' => undef,
354 '!translation' => '',
358 my $std_note = first { $_->language_id == $self->language_id } @{ $std_notes };
359 $std_note //= first { !defined $_->language_id } @{ $std_notes };
361 my $notes = $self->notes_as_stripped_html;
363 _included_note($self, %params, note => $self->transaction_description) if $self->transaction_description;
364 _included_note($self, %params, note => $notes) if $notes;
365 _included_note($self, %params, note => $std_note->translation) if $std_note;
367 $params{xml}->endTag;
368 # </rsm:ExchangedDocument>
371 sub _seller_trade_party {
372 my ($self, %params) = @_;
374 my @our_address = _parse_our_address();
376 my $sales_person = $self->salesman;
377 my $sales_person_auth = SL::DB::Manager::AuthUser->find_by(login => $sales_person->login);
378 my %sales_person_cfg = $sales_person_auth ? %{ $sales_person_auth->config_values } : ();
379 $sales_person_cfg{email} ||= $sales_person->deleted_email;
380 $sales_person_cfg{tel} ||= $sales_person->deleted_tel;
382 # <ram:SellerTradeParty>
383 $params{xml}->startTag("ram:SellerTradeParty");
384 $params{xml}->dataElement("ram:ID", _u8($self->customer->c_vendor_id)) if ($self->customer->c_vendor_id // '') ne '';
385 $params{xml}->dataElement("ram:Name", _u8($::instance_conf->get_company));
387 # <ram:DefinedTradeContact>
388 $params{xml}->startTag("ram:DefinedTradeContact");
390 $params{xml}->dataElement("ram:PersonName", _u8($sales_person_cfg{name} || $sales_person_cfg{login}));
392 if ($sales_person_cfg{tel}) {
393 $params{xml}->startTag("ram:TelephoneUniversalCommunication");
394 $params{xml}->dataElement("ram:CompleteNumber", _u8($sales_person_cfg{tel}));
395 $params{xml}->endTag;
398 if ($sales_person_cfg{email}) {
399 $params{xml}->startTag("ram:EmailURIUniversalCommunication");
400 $params{xml}->dataElement("ram:URIID", _u8($sales_person_cfg{email}));
401 $params{xml}->endTag;
404 $params{xml}->endTag;
405 # </ram:DefinedTradeContact>
408 # <ram:PostalTradeAddress>
409 $params{xml}->startTag("ram:PostalTradeAddress");
410 foreach my $element (@our_address) {
411 $params{xml}->dataElement("ram:" . $element->[0], _u8($element->[1]));
413 $params{xml}->endTag;
414 # </ram:PostalTradeAddress>
417 my $ustid_nr = $::instance_conf->get_co_ustid;
418 $ustid_nr = "DE$ustid_nr" unless $ustid_nr =~ m{^[A-Z]{2}};
419 # <ram:SpecifiedTaxRegistration>
420 $params{xml}->startTag("ram:SpecifiedTaxRegistration");
421 $params{xml}->dataElement("ram:ID", _u8($ustid_nr), "schemeID" => "VA");
422 $params{xml}->endTag;
423 # </ram:SpecifiedTaxRegistration>
425 $params{xml}->endTag;
426 # </ram:SellerTradeParty>
429 sub _buyer_trade_party {
430 my ($self, %params) = @_;
432 # <ram:BuyerTradeParty>
433 $params{xml}->startTag("ram:BuyerTradeParty");
434 $params{xml}->dataElement("ram:ID", _u8($self->customer->customernumber));
435 $params{xml}->dataElement("ram:Name", _u8($self->customer->name));
437 _customer_postal_trade_address(%params, customer => $self->customer);
439 $params{xml}->endTag;
440 # </ram:BuyerTradeParty>
443 sub _included_supply_chain_trade_line_item {
444 my ($self, %params) = @_;
447 foreach my $item (@{ $self->items }) {
448 _line_item($self, %params, item => $item, line_number => $line_number);
453 sub _applicable_header_trade_agreement {
454 my ($self, %params) = @_;
456 # <ram:ApplicableHeaderTradeAgreement>
457 $params{xml}->startTag("ram:ApplicableHeaderTradeAgreement");
459 _seller_trade_party($self, %params);
460 _buyer_trade_party($self, %params);
462 if ($self->cusordnumber) {
463 # <ram:BuyerOrderReferencedDocument>
464 $params{xml}->startTag("ram:BuyerOrderReferencedDocument");
465 $params{xml}->dataElement("ram:IssuerAssignedID", _u8($self->cusordnumber));
466 $params{xml}->endTag;
467 # </ram:BuyerOrderReferencedDocument>
470 $params{xml}->endTag;
471 # </ram:ApplicableHeaderTradeAgreement>
474 sub _applicable_header_trade_delivery {
475 my ($self, %params) = @_;
477 # <ram:ApplicableHeaderTradeDelivery>
478 $params{xml}->startTag("ram:ApplicableHeaderTradeDelivery");
479 # <ram:ActualDeliverySupplyChainEvent>
480 $params{xml}->startTag("ram:ActualDeliverySupplyChainEvent");
482 $params{xml}->startTag("ram:OccurrenceDateTime");
483 $params{xml}->dataElement("udt:DateTimeString", ($self->deliverydate // $self->transdate)->strftime('%Y%m%d'), "format" => "102");
484 $params{xml}->endTag;
486 $params{xml}->endTag;
487 # </ram:ActualDeliverySupplyChainEvent>
488 $params{xml}->endTag;
489 # </ram:ApplicableHeaderTradeDelivery>
492 sub _applicable_header_trade_settlement {
493 my ($self, %params) = @_;
495 # <ram:ApplicableHeaderTradeSettlement>
496 $params{xml}->startTag("ram:ApplicableHeaderTradeSettlement");
497 $params{xml}->dataElement("ram:InvoiceCurrencyCode", _u8(SL::Helper::ISO4217::map_currency_name_to_code($self->currency->name) // 'EUR'));
499 _taxes($self, %params);
500 _payment_terms($self, %params);
501 _totals($self, %params);
503 $params{xml}->endTag;
504 # </ram:ApplicableHeaderTradeSettlement>
507 sub _supply_chain_trade_transaction {
508 my ($self, %params) = @_;
510 # <rsm:SupplyChainTradeTransaction>
511 $params{xml}->startTag("rsm:SupplyChainTradeTransaction");
513 _included_supply_chain_trade_line_item($self, %params);
514 _applicable_header_trade_agreement($self, %params);
515 _applicable_header_trade_delivery($self, %params);
516 _applicable_header_trade_settlement($self, %params);
518 $params{xml}->endTag;
519 # </rsm:SupplyChainTradeTransaction>
525 my $prefix = $::locale->text('The ZUGFeRD invoice data cannot be generated because the data validation failed.') . ' ';
527 if (!$::instance_conf->get_co_ustid) {
528 SL::X::ZUGFeRDValidation->throw(message => $prefix . $::locale->text('The VAT registration number is missing in the client configuration.'));
531 if (!$::instance_conf->get_company || any { my $get = "get_address_$_"; !$::instance_conf->$get } qw(street1 zipcode city)) {
532 SL::X::ZUGFeRDValidation->throw(message => $prefix . $::locale->text('The company\'s address information is incomplete in the client configuration.'));
535 if ($::instance_conf->get_address_country && !SL::Helper::ISO3166::map_name_to_alpha_2_code($::instance_conf->get_address_country)) {
536 SL::X::ZUGFeRDValidation->throw(message => $prefix . $::locale->text('The country from the company\'s address in the client configuration cannot be mapped to an ISO 3166-1 alpha 2 code.'));
539 if ($self->customer->country && !SL::Helper::ISO3166::map_name_to_alpha_2_code($self->customer->country)) {
540 SL::X::ZUGFeRDValidation->throw(message => $prefix . $::locale->text('The country from the customer\'s address cannot be mapped to an ISO 3166-1 alpha 2 code.'));
543 if (!SL::Helper::ISO4217::map_currency_name_to_code($self->currency->name)) {
544 SL::X::ZUGFeRDValidation->throw(message => $prefix . $::locale->text('The currency "#1" cannot be mapped to an ISO 4217 currency code.', $self->currency->name));
547 my $failed_unit = first { !SL::Helper::UNECERecommendation20::map_name_to_code($_) } map { $_->unit } @{ $self->items };
549 SL::X::ZUGFeRDValidation->throw(message => $prefix . $::locale->text('One of the units used (#1) cannot be mapped to a known unit code from the UN/ECE Recommendation 20 list.', $failed_unit));
553 sub create_zugferd_data {
556 _validate_data($self);
558 my %ptc_data = $self->calculate_prices_and_taxes;
560 my $xml = XML::Writer->new(
568 ptc_data => \%ptc_data,
574 # <rsm:CrossIndustryInvoice>
575 $xml->startTag("rsm:CrossIndustryInvoice",
576 "xmlns:a" => "urn:un:unece:uncefact:data:standard:QualifiedDataType:100",
577 "xmlns:rsm" => "urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100",
578 "xmlns:qdt" => "urn:un:unece:uncefact:data:standard:QualifiedDataType:10",
579 "xmlns:ram" => "urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100",
580 "xmlns:xs" => "http://www.w3.org/2001/XMLSchema",
581 "xmlns:udt" => "urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100");
583 _exchanged_document_context($self, %params);
584 _exchanged_document($self, %params);
585 _supply_chain_trade_transaction($self, %params);
588 # </rsm:CrossIndustryInvoice>
593 sub create_zugferd_xmp_data {
597 conformance_level => 'EXTENDED',
598 document_file_name => 'ZUGFeRD-invoice.xml',
599 document_type => 'INVOICE',