www.tres.pl - Baza wiedzy Trawers ERP - Spis treści
KSeF. DodatkowyOpis. Klucze 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. Konfiguracja Zrozumiał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 5. Tematy powiązane Architektura programu KSeF. Opis ogólny. Konfiguracja KSeF. Moduły w Trawers ERP KSeF. Faktury a komunikaty EDI KSeF. EDI INVOICE a Faktury XML Słowa kluczowe #TrawersERP-Architektura #TrawersERP-ProcesyGospodarcze #PTU/VAT-KSeF #Pomoc-AsystentAI
www.tres.pl - Baza wiedzy Trawers ERP - Spis treści