1. Klucze wg EDI (GS1)
2. Przykłady kluczy
3. Ekran parametrów [AD_TPK21]
4. Klucze GS1 a komunikaty EDI
5. Tematy powiązane
1. Klucze wg EDI (GS1)
Organizacja GS1 Polska opracowała propozycje kluczy dodatkowych, które można stosować
w fakturach KSeF jako uzupełnienie danych istotnych z punktu widzenia procesów EDI
i modelu Order-to-Cash > Sekcja: DodatkowyOpis.
Klucze te są zgrupowane oddzielnie dla:
* dokumentu głównego (faktury),
* pozycji faktury (wierszy).
Czy warto wdrożyć te klucze w Trawers ERP?
Tak - warto je potraktować jako zalecany standard branżowy, szczególnie jeśli:
* Gdy klienci lub kontrahenci korzystają z EDI,
* System pracuje z dużymi sieciami handlowymi (retail),
* Jest integracja z systemami GS1, np. poprzez GLN, GTIN, SSCC itd.,
* Ważna jest kompatybilność z KSeF oraz unikanie niejednoznacznych
interpretacji przy wymianie dokumentów.
2. Przykłady kluczy (z dokumentu GS1)
Na poziomie dokumentu (faktury):
* `orderNumber` - numer zamówienia,
* `deliveryNoteNumber` - numer awiza dostawy,
* `sscc` - numer jednostki logistycznej (opakowania zbiorczego),
* `buyerGLN`, `supplierGLN` - identyfikatory GLN dla stron transakcji.
Na poziomie pozycji (wierszy faktury):
* `lineItemNumber` - numer pozycji w dokumencie,
* `ean`, `gtin` - kody identyfikacyjne towaru (GS1),
* `internalProductCode` - kod wewnętrzny,
* `batchNumber`, `expiryDate` - seria i data ważności.
Porównanie z Trawers ERP
Trawers obsługuje wiele z tych danych (zamówienia, identyfikatory, kody towarów, partie),
ale nie zawsze są one przenoszone do e-faktury XML zgodnie z kluczami GS1.
Zatem warto rozważyć:
* mapowanie danych Trawersa (np. z zamówienia, dokumentów WZ, partii towarowych)
do sugerowanych kluczy GS1,
* rozszerzenie eksportu do XML KSeF o te dane jako: elementy dodatkowe,
* ewentualne wdrożenie mechanizmu konfiguracji kluczy niestandardowych
(np. przez słownik nazw, jeśli GS1 się zmieni).
Czy są lepsze nazwy kluczy?
Nie. Propozycje GS1 są zgodne z międzynarodowymi standardami EDI (np. EDIFACT, PEPPOL)
i dobrze znane dużym operatorom handlowym. Użycie własnych nazw spowoduje:
* mniejszą interoperacyjność,
* konieczność mapowania przy integracjach,
* ryzyko błędów interpretacji.
Rekomendacja
Stosowanie kluczy GS1 jako standard domyślny w Trawersie, jeśli wdraża się KSeF z EDI.
Mapa kluczy GS1 <--> Trawers ERP
Poniżej znajduje się uzupełniona mapa kluczy GS1 <--> Trawers ERP, wzbogacona o kolumnę
z nazwami kluczy po polsku zgodnie z formatem XML używanym w: DodatkowyOpis` KSeF
(np. `/FA/DodatkowyOpis/Klucz['NumerAwizoDostawy']`).
POZIOM DOKUMENTU (Nagłówek faktury)
| Klucz GS1 | Klucz PL (KSeF) | Opis | Dane w Trawers ERP | Uwagi |
| -------------------- | ---------------------------- | ---------------------------- | ---------------------------------------- | --------------------------------------- |
| `orderNumber` | `NumerZamowienia` | Numer zamówienia | Numer zamówienia odbiorcy (z faktury/WZ) | Powiązanie z dokumentem źródłowym |
| `deliveryNoteNumber` | `NumerAwizoDostawy` | Numer dokumentu dostawy (WZ) | Numer dokumentu WZ | Możliwe do zaciągnięcia przy powiązaniu |
| `buyerGLN` | `GLNNabywcy` | GLN nabywcy | Kod kontrahenta -> GLN | Wymaga pola dodatkowego |
| `supplierGLN` | `GLNDostawcy` | GLN dostawcy | GLN własnej firmy | W danych firmy |
| `sscc` | `NumerJednostkiLogistycznej` | Numer jednostki logistycznej | Numer SSCC | Jeśli stosowane |
| `deliveryDate` | `DataDostawy` | Data dostawy | Data WZ lub inna zdefiniowana | |
| `invoiceIssueDate` | `DataWystawieniaFaktury` | Data wystawienia faktury | Data dokumentu | Standardowo dostępna |
| `paymentTerms` | `WarunkiPlatnosci` | Warunki płatności | Termin płatności | |
| `contractNumber` | `NumerUmowy` | Numer umowy | Numer umowy (jeśli stosowany) | Rzadziej używane |
POZIOM POZYCJI (Wiersze faktury)
| Klucz GS1 | Klucz PL (KSeF) | Opis | Dane w Trawers ERP | Uwagi |
| --------------------- | ---------------------- | ---------------------- | ----------------------------------- | ------------------------- |
| `lineItemNumber` | `NumerPozycji` | Numer pozycji | Numer pozycji | Generowany automatycznie |
| `gtin`, `ean` | `KodTowaruEAN` | Kod towaru EAN/GTIN | Kod EAN w kartotece | Pole 'Kod EAN' |
| `internalProductCode` | `KodTowaruWewnetrzny` | Kod wewnętrzny | Kod towaru | Standardowe pole |
| `batchNumber` | `NumerPartii` | Numer partii | Numer partii (jeśli stosowane) | Moduł partii/traceability |
| `expiryDate` | `DataWaznosci` | Data ważności | Data ważności partii | Wymaga rejestracji partii |
| `quantity` | `Ilosc` | Ilość | Ilość | Standardowe pole |
| `unitOfMeasure` | `JednostkaMiary` | Jednostka miary | JM z kartoteki | |
| `netPrice` | `CenaNettoJednostkowa` | Cena jednostkowa netto | Cena pozycji | |
| `discount` | `Rabat` | Rabat | Rabat pozycji (kwotowy/procentowy) | |
| `itemDescription` | `OpisPozycji` | Opis pozycji | Nazwa towaru | |
| `countryOfOrigin` | `KrajPochodzenia` | Kraj pochodzenia | Kraj pochodzenia (kartoteka towaru) | Pole dodatkowe |
Format w e-fakturze KSeF
W XML faktury wyglądałoby to przykładowo tak:
```xml
<tns:DodatkowyOpis>
<tns:Klucz>NumerZamowienia</tns:Klucz>
<tns:Wartosc>ZAM/123/2025</tns:Wartosc>
</tns:DodatkowyOpis>
<tns:DodatkowyOpis>
<tns:Klucz>NumerAwizoDostawy</tns:Klucz>
<tns:Wartosc>AWZ/456/2025</tns:Wartosc>
</tns:DodatkowyOpis>
```
POZIOM DOKUMENTU (Nagłówek faktury)
| Klucz PL (KSeF) | Klucz EN (GS1) | Dane w Trawers ERP | Uwagi |
| -------------------------- | -------------------- | -------------------------------------------- | ----------------------------- |
| NumerZamowienia | `orderNumber` | Numer zamówienia odbiorcy | Z pola zamówienia powiązanego |
| NumerAwizoDostawy | `deliveryNoteNumber` | Numer dokumentu WZ | Z dokumentów powiązanych |
| GLNNabywcy | `buyerGLN` | GLN z kartoteki kontrahenta | Wymaga pola GLN |
| GLNDostawcy | `supplierGLN` | GLN firmy (z danych nagłówkowych) | Ustalone globalnie |
| NumerJednostkiLogistycznej | `sscc` | Numer SSCC z etykiet logistycznych | Jeśli stosowane |
| DataDostawy | `deliveryDate` | Data WZ lub dostawy | Może być wyliczana |
| DataWystawieniaFaktury | `invoiceIssueDate` | Data dokumentu | Standardowe pole |
| WarunkiPlatnosci | `paymentTerms` | Termin płatności z faktury | Z warunków płatności |
| NumerUmowy | `contractNumber` | Numer umowy z kontrahentem (jeśli stosowany) | Może wymagać pola dodatkowego |
POZIOM POZYCJI (Wiersze faktury)
| Klucz PL (KSeF) | Klucz EN (GS1) | Dane w Trawers ERP | Uwagi |
| -------------------------- | ---------------------- | ---------------------------------- | ---------------------------------------- |
| NumerPozycji | `lineItemNumber` | Numer pozycji | Automatyczne |
| KodTowaruEAN | `gtin` / `ean` | Kod EAN z kartoteki | Pole: Kod EAN |
| KodTowaruWewnetrzny | `internalProductCode` | Kod towaru | Główny identyfikator |
| NumerPartii | `batchNumber` | Numer partii z dokumentu | Jeśli włączone partie |
| DataWaznosci | `expiryDate` | Data ważności towaru (partii) | Z danych partii |
| Ilosc | `quantity` | Ilość pozycji | Standardowo dostępna |
| JednostkaMiary | `unitOfMeasure` | Jednostka miary | Z kartoteki lub dokumentu |
| CenaNettoJednostkowa | `netPrice` | Cena pozycji | Po rabacie, netto |
| Rabat | `discount` | Rabat pozycji | Kwotowy lub procentowy |
| OpisPozycji | `itemDescription` | Nazwa towaru | Z kartoteki |
| KrajPochodzenia | `countryOfOrigin` | Kraj pochodzenia | Jeśli wypełnione w kartotece |
| WagaBrutto | `grossWeight` | Waga brutto towaru | Może być w polu dodatkowym |
| WagaNetto | `netWeight` | Waga netto | Jak wyżej |
| TypOpakowania | `packagingType` | Rodzaj opakowania | Wymaga pola dodatkowego |
| NazwaOpakowania | `packagingDescription` | Opis/nazwa opakowania | J.w. |
| LiczbaJednostekWOpakowaniu | `unitsPerPackage` | Ilość sztuk w opakowaniu zbiorczym | Czasem w polu 'ILO_PACZ' lub równoważnym |
Klucze dodatkowe - tłumaczenie PL -> EN
| Klucz PL (KSeF) | Proponowany klucz EN (GS1 style) |
| -------------------------- | --------------------------------------- |
| NumerZamowienia | `orderNumber` |
| NumerAwizoDostawy | `deliveryNoteNumber` |
| GLNNabywcy | `buyerGLN` |
| GLNDostawcy | `supplierGLN` |
| NumerJednostkiLogistycznej | `sscc` (Serial Shipping Container Code) |
| DataDostawy | `deliveryDate` |
| DataWystawieniaFaktury | `invoiceIssueDate` |
| WarunkiPlatnosci | `paymentTerms` |
| NumerUmowy | `contractNumber` |
| NumerPozycji | `lineItemNumber` |
| KodTowaruEAN | `gtin` lub `ean` |
| KodTowaruWewnetrzny | `internalProductCode` |
| NumerPartii | `batchNumber` |
| DataWaznosci | `expiryDate` |
| Ilosc | `quantity` |
| JednostkaMiary | `unitOfMeasure` |
| CenaNettoJednostkowa | `netPrice` |
| Rabat | `discount` |
| OpisPozycji | `itemDescription` |
| KrajPochodzenia | `countryOfOrigin` |
| WagaBrutto | `grossWeight` |
| WagaNetto | `netWeight` |
| TypOpakowania | `packagingType` |
| NazwaOpakowania | `packagingDescription` |
| LiczbaJednostekWOpakowaniu | `unitsPerPackage` |
3. Ekran parametrów [AD_TPK21]
Ocena obecnego sposobu definiowania 'Dodatkowego Opisu' na fakturze KSeF
Wg [AD_TPK21]
Patrz też:
KSeF. Opis ogólny. KonfiguracjaZrozumiałość
Sposób jest czytelny i intuicyjny:
* użytkownik zaznacza T przy polu, które ma zostać uwzględnione na fakturze KSeF,
* dane są mapowane do odpowiednich kluczy KSeF (np. `WagaNetto`, `NumerPartii`),
* wartości są pobierane dynamicznie z dokumentu (nagłówka lub pozycji).
Dla użytkownika końcowego (np. wystawiającego fakturę) interfejs jest prosty i funkcjonalny
Wystarczy zaznaczenie checkboxa lub pola tekstowego, by dane zostały umieszczone w e-fakturze.
Skuteczność
Ten sposób:
* pozwala w pełni kontrolować, które dane trafiają do faktury KSeF,
* umożliwia dynamiczne generowanie wartości w zależności od dokumentu,
* jest zgodny z wymogami KSeF i specyfikacją GS1 (poprzez przypisanie nazw kluczy),
* umożliwia łatwe rozszerzanie listy obsługiwanych pól w przyszłości.
Alternatywne podejścia (dla porównania)1. Słownik kluczy per klient / typ dokumentu
* Mniej elastyczne na poziomie użytkownika,
* konfiguracja bardziej techniczna,
* lepsze przy integracjach masowych (EDI, eksport XML automatyczny).
2. Automatyczne reguły (bez interfejsu użytkownika)
* np. jeśli towar ma EAN zawsze dodaj `KodTowaruEAN`
* trudniejsze do utrzymania i mniej przejrzyste dla użytkownika.
3. Makra lub skrypty z zewnętrznej logiki
* np. generowanie opisu na podstawie szablonów XML lub JSON,
* bardziej elastyczne, ale mniej dostępne dla użytkownika końcowego.
Rekomendacja
Obecny sposób:
* jest zrozumiały, skuteczny i ergonomiczny,
* pozwala użytkownikowi świadomie wybrać, co pojawi się na e-fakturze,
* łatwo go rozszerzyć o nowe pola.
Zalecam jego utrzymanie jako głównego mechanizmu konfiguracji danych do pola:
DodatkowyOpis` w KSeF.
Można natomiast:
* rozważyć dodanie opcji podglądu wynikowego XML/JSON przed wysyłką,
* wprowadzić profilowanie ustawień per kontrahent (jeśli różne wymagania EDI/KSeF).
4. Klucze GS1 a komunikaty EDI
4.1 Rola oznaczeń
Klucze wg EDI (GS1)
GS1 daje propozycje nazw kluczy do użycia w KSeF w sekcji DodatkowyOpis.
Tzn. KSeF ma swój schemat, a GS1 mówi: jeśli chcesz przekazać dane EDI w polu dodatkowym,
używaj takich kluczy.
EDI (ECOD)
To pełny format komunikatów EDI w XML (np. ECOD XML INVOIC, ECOD XML ORDER).
Nie ma 'kluczy dodatkowych', tylko z góry zdefiniowane elementy XML typu <BuyerOrderNumber>,
<EAN>, <DeliveryDate> itd.
4.2 Różnice i podobieństwa oznaczeń
Różnice: styl nazw i rola danych
* Konwencja nazewnicza
GS1: camelCase (orderNumber, deliveryNoteNumber)
EDI: PascalCase w XML (<BuyerOrderNumber>, <DespatchAdviceNumber>)
* Poziomy danych
GS1: Rozdzielone logicznie: dokument / pozycja
EDI: Rozdzielone strukturalnie: <Invoice-Header>, <Invoice-Lines>, sekcje Delivery/Order/Line
* Cel
GS1: Dodatkowe informacje w KSeF
EDI: pełna wymiana dokumentów (zamówienia, faktury, awiza itd.)
Podobieństwa
Poziom dokumentu
GS1: orderNumber
EDI: <BuyerOrderNumber> lub <OrderNumber>
Rozróżnia się: zamówienie kupującego vs ogólne: OrderNumber zależnie od dokumentu/sekcji
GS1: deliveryNoteNumber
EDI: <DespatchAdviceNumber>
GS1: invoiceIssueDate
EDI: <InvoiceDate>
Także inne daty, np. <InvoicePostDate>
GS1: buyerGLN
EDI: <Buyer><ILN> / <Buyer><GLN>
EDI opisuje ILN/GLN jako równoważne identyfikatory lokalizacji
GS1: supplierGLN
EDI <Seller><ILN> / <Seller><GLN>
Poziom pozycji (wiersz faktury)
GS1: lineItemNumber
EDI: <LineNumber>
Bezpośredni odpowiednik
GS1: gtin / ean
EDI: <EAN>
Główny identyfikator produktu
GS1: internalProductCode
EDI: <SupplierItemCode> (często) lub <BuyerItemCode> (zależnie od strony)
Dwa kody: 'wg dostawcy' i 'wg nabywcy'
GS1: expiryDate
EDI: <ExpirationDate> albo <BestBeforeDate>
Rozróżnia 'ważność' vs 'najlepiej spożyć przed'
GS1: quantity
EDI: <InvoiceQuantity> Dla zamówień <OrderedQuantity>
GS1: netPrice
EDI: <InvoiceUnitNetPrice> Dla zamówień <OrderedUnitNetPrice>
GS1: unitsPerPackage
EDI: <InvoiceUnitPacksize>
Pułapki znaczeniowe
1. Order number
* GS1: jeden klucz `orderNumber`.
* EDI: rozróżnia 'numer zamówienia kupującego' (`<BuyerOrderNumber>`) i inne numery
zamówień w zależności od kontekstu.
2. Kody produktu
* GS1: `internalProductCode` zwykle = kod dostawcy/sprzedawcy (wewnętrzny).
* EDI: rozdzielenie:
* `<SupplierItemCode>` = kod wg dostawcy,
* `<BuyerItemCode>` = kod wg kupującego.
W KSeF (DodatkowyOpis) trzeba zdecydować, które klucze stosować
3. Daty ważności
* GS1: `expiryDate`.
* EDI: dwa pola: `<ExpirationDate>` i `<BestBeforeDate>`.
W branży spożywczej: 'best before'# 'expiration'.
4. GLN/ILN
* GS1 nazywa wprost `buyerGLN`, `supplierGLN`.
* EDI stosuje 'ILN/GLN' i używa w wielu rolach (Buyer, Seller, DeliveryPoint, DeliveryLocationNumber).
Mapowanie do GS1 jest proste, ale trzeba pilnować roli (kto jest kim w transakcji).
Rekomendacja wdrożeniowa w Trawers ERP
Aby zachować podstawową spójność EDI + KSeF:
* Na wyjściu do KSeF stosować klucze GS1 (camelCase) w `DodatkowyOpis`,
bo to jest 'język interoperacyjny' dla KSeF.
* W integracji EDI stosować mapowanie:
* EDI tag -> 'pole logiczne w Trawersie' -> GS1 key (do KSeF),
* i odwrotnie przy importach (np. zamówienia EDI ORDER -> dokumenty w Trawersie).
* Realizować jako słownik translacji (nie twardo w kodzie), bo:
* EDI i GS1 mogą mieć rozszerzenia,
* a klienci potrafią wymagać swoich wariantów (np. dodatkowe referencje).
4.3 Potrzeba integracji (interoperacyjności)
EDI to komunikaty (ORDER/INVOIC/DESADV) z precyzyjnymi definicjami danych i logiką integracji.
KSeF > DodatkowyOpis, to dodatkowe metadane w e-fakturze KSeF (w praktyce 'koszyk' na informacje,
które nie mają miejsca w schemie KSeF albo mają znaczenie dla biznesu/EDI).
W typowym wdrożeniu:
* komunikaty EDI przekazują dane 'wg EDI'
* faktury KSeF generuje się 'wg KSeF'
Nie ma potrzeby szukania analogii definicji ani budowania mechanizmu pełnego dopasowania
(mapowania) GS1 <--> EDI.
Wspólne identyfikatory
Jednakże takie mapowanie jest przydatne w dwóch sytuacjach:
1. KSeF jest jedynym źródłem dla odbiorcy, a odbiorca oczekuje danych 'EDI-owych'
w fakturze (bo np. ich procesy matchingu/rozliczeń tak działają).
Wtedy DodatkowyOpis robi za 'most' informacyjny.
2. Chcemy uzyskać spójności referencji między kanałami (EDI <--> KSeF),
np. aby sieć handlowa mogła łatwo skojarzyć:
* numer zamówienia,
* numer awiza/dostawy,
* GLN,
* SSCC,
* numery pozycji / EAN.
W takich sytuacjach: 1./2. warto wykorzystać kluczowe identyfikatory
jako wspólne dla EDI i dla DodatkowyOpis w KSeF (wg GS1).
Dotyczy to tylko kilku identyfikatorów, które realnie pomagają w uzgadnianiu
dokumentów (order, despatch, GLN, EAN/GTIN, SSCC, line).
4.3 Realizacja w Trawers ERP (koncepcja)
Rozbudować Parametry KSeF. Klasyfikacja. Opis [AD_TPK21] o profil: 'EDI'
Teraz jest wyróżniony profil: 'GS1'
Dopisać klucze z pakietu EDI (minimalny). Użytkownicy oznaczą [T] potrzebne klucze.
Dane do tych kluczy zasilać do DodatkowyOpis z tych samych źródel co EDI:
(zamówienia powiązane, WZ/DESADV, kartoteki GLN/EAN, indeksy obce, partie).
Poniżej w .prg są tabele profili do zasilania.
(opisy wewnętrzne)
Profil 1: Retail / EDI matching standard (zalecany 'domyślny')
Profil 2: FMCG / Traceability (retail + partie + daty)
Profil 3: B2B light (minimum danych, maksimum efektu)
Reguła wdrożeniowa (żeby nie 'przeładować' DodatkowyOpis)
* Profil 1 jako domyślny dla retail/EDI.
* Profil 2 tylko gdy realnie używane partie/daty/SSCC.
* Profil 3 dla reszty kontrahentów (prosto i skutecznie).
NOTE: to są profile 'ogólne' zaproponowane przez AsystentAI.
Do ew. uwzględnienia są także potrzeby (profile) wymagane przez
poszczególnych odbiorców, np. Castorama, OBI, ...
Patrz też:
KSeF. EDI INVOICE a Faktury XML