E-faktury w sgcSign 2026.12: tworzenie, walidacja i podpisywanie faktury

· Komponenty
E-faktury w sgcSign 2026.12, tworzenie, walidacja i podpisywanie faktur w Delphi i .NET

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:

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:

Obsługiwane są też dwa hiszpańskie systemy podatkowe:

FormatKlasaZapisOdczyt
UBL 2.1 Invoice i CreditNoteTsgcInvoiceUBLTakTak
UN/CEFACT CII D16BTsgcInvoiceCIITakTak
XRechnung, UBL lub CIITsgcInvoiceDocumentTakTak
Peppol BIS Billing 3.0, UBLTsgcInvoiceDocumentTakTak
Factur-X / ZUGFeRD XML, pięć profiliTsgcInvoiceFacturXTakTak
Facturae 3.2, 3.2.1 i 3.2.2TsgcInvoiceFacturaeTakNie
FatturaPA 1.2.3TsgcInvoiceFatturaPATakNie
KSeF FA(3)TsgcInvoiceKSeFTakNie
Rekordy VeriFactuTsgcInvoiceVeriFactuTakNie
TicketBAI 1.2.2TsgcInvoiceTicketBAITakNie

Wysyłanie faktury

Trzy klienty dostarczają dokument do organu podatkowego:

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:

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.

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.