Do tej pory sgcSign podpisywał plik XML faktury, który aplikacja musiała zbudować samodzielnie. Profile krajowe potrafiły podpisać plik Facturae, FatturaPA lub TicketBAI, ale plik musiał już istnieć, a jego utworzenie należało do Ciebie.
Od wersji sgcSign 2026.12 biblioteka tworzy także samą fakturę. Wypełniasz typowaną fakturę, biblioteka oblicza sumy, sprawdza reguły biznesowe i zapisuje dokument w formacie wymaganym przez odbiorcę lub organ podatkowy. Profile krajowe podpisują wynik, a trzy klienty go wysyłają. Wszystko, co opisano w tym wpisie, jest dostępne od wersji sgcSign 2026.12, dla Delphi 7 do Delphi 13 oraz .NET, i wchodzi w skład sgcSign.
Faktury elektroniczne w sgcSign w minutę: model faktury, formaty, walidacja i wysyłka przez Peppol. Również w serwisie YouTube.
Typowana faktura oparta na EN 16931
TsgcInvoice to typowany model semantycznego modelu danych EN 16931: sprzedawca, nabywca, odbiorca płatności, płatność, pozycje, rabaty i opłaty dodatkowe, zestawienie VAT oraz sumy. Model nie zawiera XML, więc tę samą fakturę można zapisać w więcej niż jednej składni. CalculateTotals wypełnia kwoty netto pozycji, zestawienie VAT i sumy dokumentu, dzięki czemu aplikacja ustawia tylko ilości, ceny i stawki VAT i niczego sama nie sumuje.
TsgcInvoiceUBL zapisuje i odczytuje UBL 2.1 Invoice oraz CreditNote (faktura korygująca lub nota kredytowa). TsgcInvoiceCII zapisuje i odczytuje UN/CEFACT Cross Industry Invoice D16B. Poniższy przykład wypełnia fakturę, oblicza sumy, sprawdza reguły EN 16931 i zapisuje plik UBL 2.1.
uses
Classes, SysUtils,
sgcSign_Invoice, sgcSign_Invoice_UBL, sgcSign_Invoice_Validator;
procedure CreateInvoice;
var
oInvoice: TsgcInvoice;
oLine: TsgcInvoiceLine;
oValidator: TsgcInvoiceValidator;
oUBL: TsgcInvoiceUBL;
begin
oInvoice := TsgcInvoice.Create;
oValidator := TsgcInvoiceValidator.Create;
oUBL := TsgcInvoiceUBL.Create;
try
oInvoice.Number := 'INV-2026-0001';
oInvoice.IssueDate := EncodeDate(2026, 11, 11);
oInvoice.DueDate := EncodeDate(2026, 12, 11);
oInvoice.CurrencyCode := 'EUR';
oInvoice.SpecificationIdentifier :=
CS_SGC_INVOICE_UBL_CUSTOMIZATION_EN16931;
oInvoice.BuyerReference := 'PO-7781';
oInvoice.Seller.Name := 'Seller Company SL';
oInvoice.Seller.VATID := 'ESB12345674';
oInvoice.Seller.Address.City := 'Madrid';
oInvoice.Seller.Address.CountryCode := 'ES';
oInvoice.Buyer.Name := 'Buyer Company GmbH';
oInvoice.Buyer.VATID := 'DE123456789';
oInvoice.Buyer.Address.City := 'Berlin';
oInvoice.Buyer.Address.CountryCode := 'DE';
oLine := oInvoice.Lines.Add;
oLine.ID := '1';
oLine.Item.Name := 'Consulting';
oLine.Quantity := 10;
oLine.UnitCode := CS_SGC_INVOICE_UNIT_HOUR;
oLine.Price.NetPrice := 85;
oLine.VATCategoryCode := CS_SGC_INVOICE_VAT_STANDARD;
oLine.VATRate := 21;
// line amounts, VAT breakdown and totals
oInvoice.CalculateTotals;
// EN 16931 business rules
if not oValidator.Validate(oInvoice) then
raise Exception.Create(oValidator.AsText);
// UBL 2.1 document
oUBL.WriteToFile(oInvoice, 'invoice.xml');
finally
oUBL.Free;
oValidator.Free;
oInvoice.Free;
end;
end;
XRechnung, Peppol BIS i Factur-X
Większość odbiorców nie wymaga czystego EN 16931. Wymaga jego profilu. sgcSign 2026.12 zapisuje i odczytuje trzy z nich na podstawie tego samego modelu:
- XRechnung, w składni UBL lub CII.
- Peppol BIS Billing 3.0, w składni UBL.
- Factur-X / ZUGFeRD, XML pięciu profili: Minimum, Basic WL, Basic, EN 16931 i Extended, za pośrednictwem
TsgcInvoiceFacturX.
Zapis profilu nie zmienia faktury, więc jeden model można zapisać jako XRechnung dla jednego klienta, a jako Peppol BIS dla następnego. Gdy nadchodzi faktura, sgcInvoiceReadAny wykrywa składnię i profil pliku oraz wczytuje go do modelu.
Walidacja z oficjalnymi identyfikatorami reguł
TsgcInvoiceValidator sprawdza fakturę względem reguł biznesowych EN 16931 oraz, na życzenie, względem zestawów reguł XRechnung i Peppol BIS Billing 3.0. Reguły są zakodowane natywnie i działają na modelu, zanim powstanie jakikolwiek XML. Każdy komunikat zawiera oficjalny identyfikator reguły, ważność, termin biznesowy, ścieżkę pola w modelu i treść reguły, dzięki czemu aplikacja może pokazać użytkownikowi, które pole należy poprawić.
Poniższy przykład waliduje tę samą fakturę dwukrotnie. Najpierw przechodzi ona reguły EN 16931, a potem jest sprawdzana jako XRechnung, który wymaga kontaktu sprzedawcy, niewymaganego przez model podstawowy. FillInvoice wypełnia fakturę z pierwszego przykładu oraz dodaje ulicę i kod pocztowy obu stron i przelew SEPA, których wymaga XRechnung. Log wypisuje wiersz.
uses
SysUtils, Classes,
sgcSign_Invoice, sgcSign_Invoice_Validator, sgcSign_Invoice_Variants;
procedure RuleSetsSample;
var
oInvoice: TsgcInvoice;
oValidator: TsgcInvoiceValidator;
i: Integer;
begin
oInvoice := TsgcInvoice.Create;
oValidator := TsgcInvoiceValidator.Create;
try
FillInvoice(oInvoice);
oInvoice.CalculateTotals;
Log(BoolToStr(oValidator.Validate(oInvoice), True)); // True
// the same invoice as XRechnung
sgcInvoiceApplyVariant(oInvoice, ivXRechnung, isUBL);
oValidator.RuleSets := [vrsEN16931, vrsXRechnung];
if not oValidator.Validate(oInvoice) then
for i := 0 to oValidator.Messages.Count - 1 do
Log(oValidator.Messages[i].RuleID + ' ' + oValidator.Messages[i].Path);
// what XRechnung asks for and the core model does not
oInvoice.Seller.Contact.Name := 'Ana Lopez';
oInvoice.Seller.Contact.Telephone := '+34 910 000 000';
oInvoice.Seller.Contact.Email := 'ana@seller.example';
oInvoice.Delivery.ActualDeliveryDate := EncodeDate(2026, 11, 10);
Log(BoolToStr(oValidator.Validate(oInvoice), True)); // True
Log(IntToStr(oValidator.WarningCount)); // 0
finally
oValidator.Free;
oInvoice.Free;
end;
end;
Druga walidacja wypisuje dwa komunikaty, BR-DE-2 Seller.Contact i BR-DE-TMP-32 Delivery.ActualDeliveryDate. Pierwszy jest błędem krytycznym, drugi ostrzeżeniem. Po ustawieniu kontaktu i daty dostawy faktura przechodzi walidację bez ostrzeżeń.
Formaty krajowe
Trzy kraje używają własnego formatu faktury, a każdy z nich ma moduł zapisu przyjmujący ten sam TsgcInvoice:
- Facturae, Hiszpania:
TsgcInvoiceFacturaezapisuje wersje 3.2, 3.2.1 i 3.2.2. - FatturaPA, Włochy:
TsgcInvoiceFatturaPAzapisuje wersję 1.2.3 dla odbiorców prywatnych (FPR12) i dla administracji publicznej (FPA12). - KSeF, Polska:
TsgcInvoiceKSeFzapisuje fakturę ustrukturyzowaną, schemat FA(3).
Obsługiwane są też dwa hiszpańskie systemy podatkowe:
- VeriFactu:
TsgcInvoiceVeriFactubuduje rekordy rejestracji i anulowania ze łańcuchowym skrótem SHA-256, utrzymuje łańcuch między rekordami i tworzy adres URL oraz obraz kodu QR. - TicketBAI:
TsgcInvoiceTicketBAIbuduje pliki faktury i anulowania w wersji 1.2.2 z powiązaniem z poprzednią fakturą. Po podpisaniu zwraca identyfikator TBAI i kod QR.
| Format | Klasa | Zapis | Odczyt |
|---|---|---|---|
| UBL 2.1 Invoice i CreditNote | TsgcInvoiceUBL | Tak | Tak |
| UN/CEFACT CII D16B | TsgcInvoiceCII | Tak | Tak |
| XRechnung, UBL lub CII | TsgcInvoiceDocument | Tak | Tak |
| Peppol BIS Billing 3.0, UBL | TsgcInvoiceDocument | Tak | Tak |
| Factur-X / ZUGFeRD XML, pięć profili | TsgcInvoiceFacturX | Tak | Tak |
| Facturae 3.2, 3.2.1 i 3.2.2 | TsgcInvoiceFacturae | Tak | Nie |
| FatturaPA 1.2.3 | TsgcInvoiceFatturaPA | Tak | Nie |
| KSeF FA(3) | TsgcInvoiceKSeF | Tak | Nie |
| Rekordy VeriFactu | TsgcInvoiceVeriFactu | Tak | Nie |
| TicketBAI 1.2.2 | TsgcInvoiceTicketBAI | Tak | Nie |
Wysyłanie faktury
Trzy klienty dostarczają dokument do organu podatkowego:
TsgcVeriFactuClientprzesyła rekordy VeriFactu do usługi sieciowej AEAT. Odczytuje wynik każdego rekordu, stosuje limit rekordów i czas oczekiwania między przesłaniami, odpytuje o przesłane rekordy i zapisuje potwierdzenia.TsgcSdIClientwysyła plik FatturaPA do usługi sieciowej włoskiego Sistema di Interscambio (SdI), sprawdza regułę nazwy pliku i odczytuje pliki powiadomień zwracane przez SdI.TsgcKSeFOnlineClientwysyła faktury do KSeF w sesji interaktywnej: otwiera sesję, wysyła fakturę, odczytuje jej status i numer KSeF, zamyka sesję i pobiera potwierdzenie UPO.
Wysyłka przez sieć Peppol
Wersja 2026.12 wysyła też fakturę przez sieć Peppol, w Delphi i .NET. Części są osobnymi klasami, więc można użyć całego procesu albo tylko jednego jego kroku:
TsgcPeppolSMPClientwyszukuje uczestnika przez SML i SMP i weryfikuje podpisaną odpowiedź SMP.TsgcPeppolSBDHisgcPeppolWrapInvoicezapisują kopertę komunikatu biznesowego Peppol, czyli SBDH.TsgcPeppolAS4MessageiTsgcPeppolAS4Receiptimplementują komunikat AS4 profilu Peppol AS4: podpisany algorytmem RSA-SHA256, ładunek skompresowany gzip i zaszyfrowany AES-128-GCM, transport klucza RSA-OAEP.TsgcPeppolClientwykonuje wyszukiwanie, kopertę, wysyłkę i weryfikację potwierdzenia w jednym wywołaniu, z użyciemSendInvoiceiResend. Zapisuje podpisane potwierdzenie i zwraca obiekt wyniku z kodami błędów.
Nie są potrzebne żadne zewnętrzne biblioteki: kod kryptografii, XML i AS4 jest częścią biblioteki, dla Delphi 7 do Delphi 13. Poniższy przykład wysyła plik faktury za pomocą TsgcPeppolClient.
uses
Classes, SysUtils,
sgcSign_Interfaces, sgcSign_Peppol_Client;
procedure SendInvoiceToPeppol(const aAccessPointKey: IsgcKeyProvider);
var
oClient: TsgcPeppolClient;
oResult: TsgcPeppolSendResult;
begin
oClient := TsgcPeppolClient.Create(nil);
oResult := TsgcPeppolSendResult.Create;
try
// key and certificate of the sending access point
oClient.KeyProvider := aAccessPointKey;
oClient.TestNetwork := True;
// the company that issues the invoice and its country
oClient.SenderID := '0088:7315458756324';
oClient.CountryC1 := 'ES';
// lookup, envelope, AS4 message, POST and receipt in one call
if oClient.SendInvoiceFile('invoice.xml', '9915:receiver', oResult) then
WriteLn('Delivered, message ' + oResult.MessageId)
else
WriteLn(oResult.ErrorCode + ': ' + oResult.ErrorText);
finally
oResult.Free;
oClient.Free;
end;
end;
Przeczytaj wymagania, zanim zaplanujesz projekt wokół tej funkcji. Wysyłka w sieci Peppol wymaga bycia akredytowanym punktem dostępowym Peppol (dostawcą usług) z certyfikatem punktu dostępowego wydanym przez OpenPeppol. Biblioteka implementuje protokół i nie dostarcza certyfikatu ani akredytacji. Firmy korzystające z dostawcy usług zwykle wysyłają za jego pośrednictwem. Biblioteka tylko wysyła: nie ma punktu dostępowego odbierającego ani raportowania Peppol. Wyszukiwanie uczestnika nie wymaga certyfikatu.
Nadawca został przetestowany pod kątem interoperacyjności z serwerem AS4 open source phase4 (wersja 4.9.0) na lokalnej testowej PKI: każdy komunikat został przyjęty, a każde potwierdzenie zweryfikowane, z bibliotekami Delphi i .NET. Nie był uruchamiany na produkcyjnym punkcie dostępowym ani z prawdziwymi certyfikatami Peppol. Dema Demos\Delphi\Peppol i Demos\CBuilder\Peppol są dołączone do biblioteki.
Jeden komponent dla całego procesu
TsgcInvoiceDocument łączy te kroki. Wybierz format, wypełnij fakturę i wywołaj Build. Komponent oblicza sumy, waliduje według zestawów reguł formatu, zapisuje dokument i podpisuje go profilem podpisu danego formatu. Gdy walidacja się nie powiedzie, nic nie jest zapisywane, a dokument może podpisać dowolny dostawca kluczy sgcSign.
Poniższy przykład zapisuje XML Factur-X w profilu EN 16931 i podpisuje go certyfikatem z pliku PFX.
uses
Classes, SysUtils,
sgcSign_Types, sgcSign_KeyProvider_PFX,
sgcSign_Invoice, sgcSign_Invoice_Document;
procedure BuildSignedInvoice;
var
oKeyProvider: TsgcPFXKeyProvider;
oDocument: TsgcInvoiceDocument;
begin
oKeyProvider := TsgcPFXKeyProvider.Create(nil);
oDocument := TsgcInvoiceDocument.Create(nil);
try
oKeyProvider.FileName := 'certificate.pfx';
oKeyProvider.Password := 'secret';
oKeyProvider.LoadFromFile;
// FillInvoice sets seller, buyer and lines as in the previous example
FillInvoice(oDocument.Invoice);
oDocument.Format := ifFacturXEN16931;
oDocument.Sign := True;
oDocument.KeyProvider := oKeyProvider;
// totals, validation, Factur-X XML and XAdES signature
oDocument.BuildToFile('factur-x.xml');
finally
oDocument.Free;
oKeyProvider.Free;
end;
end;
Komponent potrafi także odczytywać. LoadFromFile przyjmuje plik UBL lub CII, ustawia Format zgodnie z zawartością pliku i wypełnia model, więc otrzymaną fakturę można zwalidować i zapisać ponownie w innej składni.
Czego nie ma w zakresie
Zakres tej pierwszej wersji ma ograniczenia i lepiej je poznać, zanim zaplanujesz wokół niej projekt.
- Formaty krajowe są tylko do zapisu. UBL i CII, wraz z wariantami XRechnung, Peppol BIS i Factur-X, można odczytać z powrotem do modelu. Facturae, FatturaPA, KSeF, VeriFactu i TicketBAI nie.
- Wysyłka Peppol wymaga akredytowanego punktu dostępowego i jest tylko wysyłką. Biblioteka implementuje protokół i nie dostarcza certyfikatu punktu dostępowego ani akredytacji. Nie ma punktu dostępowego odbierającego ani raportowania Peppol.
- Factur-X to tylko XML. Faktura Factur-X lub ZUGFeRD to plik PDF/A-3 z osadzonym tym XML. Komponent zapisuje XML i nie osadza go w pliku PDF/A-3.
- Faktury KSeF komponent wysyła, ale nie podpisuje, ponieważ KSeF nie podpisuje XML faktury.
- Punkty końcowe SdI nie są wbudowane. SdI przekazuje nadawcy swoje punkty końcowe podczas akredytacji kanału, a Ty ustawiasz je w kliencie.
Jak to zdobyć
E-faktury są częścią sgcSign od wersji 2026.12. To nie jest osobna edycja: jednostki są dostarczane z sgcSign, z pełnym kodem źródłowym, dla Delphi 7 do Delphi 13 oraz .NET. Nowe demo EInvoice w folderze Demos wypełnia w formularzu jedną typowaną fakturę i buduje ją w każdym z formatów za pomocą jednego komponentu.
E-faktury na stronie produktu · Pobierz wersję próbną · Lista zmian
Pytania lub uwagi? Skontaktuj się z nami, odpowiedzą Ci osoby, które napisały ten kod.
