KSeF API jednostki wewnętrzne (IdWew) – zarządzanie i nadawanie
Jednostki wewnętrzne (IdWew) w KSeF
W KSeF podstawowym identyfikatorem podatnika jest NIP. W modelu bez dodatkowych mechanizmów osoby uprawnione do działania w imieniu podatnika mają potencjalnie dostęp do wszystkich jego faktur. Dla dużych podmiotów (wiele oddziałów, zakładów, jednostek organizacyjnych) taki dostęp często jest nie do przyjęcia. Ministerstwo Finansów udostępnia mechanizm identyfikatora wewnętrznego jednostki (IdWew), dzięki któremu można zawęzić uprawnienia do konkretnych jednostek wewnętrznych bez tworzenia nowych NIP.
IdWew to unikalny identyfikator zakładu, oddziału lub innej wyodrębnionej jednostki wewnętrznej podatnika. Tworzy się go w KSeF według zasad ze specyfikacji interfejsu. Składa się z NIP podatnika oraz ciągu znaków numerycznych, np. w formacie 1111111111-33334.
Stosowanie IdWew nie jest obowiązkowe; zależy od potrzeb organizacyjnych. Wdrożenie wymaga zaprojektowania struktury uprawnień, poprawnego oznaczania faktur w strukturze FA(3) oraz powiązania identyfikatorów z procesami biznesowymi podatnika.
IdWew nie jest generowany automatycznie przez system. Podatnik sam nadaje identyfikator jednostce podrzędnej, zgodnie z wymaganym formatem (NIP + 5 cyfr), i wskazuje go jako InternalId przy nadawaniu uprawnień administratorowi jednostki podrzędnej (endpoint POST /permissions/subunits/grants, wymagane uprawnienie SubunitManage). KSeF weryfikuje wyłącznie zgodność identyfikatora z wymaganym formatem.
Instrukcja krok po kroku
1. Zrozum strukturę IdWew
IdWew składa się z NIP podatnika (10 cyfr), myślnika oraz dokładnie 5 cyfr, np. 1234567890-00001. Format ten wynika wprost ze schematu XSD faktury (typ TNIPIdWew). Nie jest to suma kontrolna obliczana algorytmicznie - to identyfikator, który podatnik samodzielnie nadaje jednostce podrzędnej i który musi tylko spełniać ten wzorzec. IdWew nie jest NIP-em i nie zastępuje NIP sprzedawcy ani nabywcy.
2. Nadaj IdWew jednostce podrzędnej
Podatnik samodzielnie ustala wartość IdWew (InternalId) dla jednostki podrzędnej, zachowując wymagany format NIP-5cyfr. Identyfikator wskazuje się jako contextIdentifier typu InternalId przy nadawaniu uprawnień administratorowi jednostki podrzędnej przez endpoint POST /permissions/subunits/grants (wymaga uprawnienia SubunitManage). Po nadaniu można zapisać identyfikator w swoim systemie (np. w danych klienta lub jednostki) i używać przy wystawianiu faktur. Szczegóły opisuje dokumentacja API KSeF 2.0 (sekcja Uprawnienia).
3. Przypisz IdWew jednostkom i pracownikom
Przypisz nadane IdWew do oddziałów, zakładów lub pracowników zgodnie z przyjętą strukturą organizacyjną. Dzięki temu w fakturach będzie widać, która jednostka wewnętrzna jest odpowiedzialna za dane dokumenty. KSeF nie weryfikuje, czy IdWew odpowiada rzeczywistej jednostce; nadzór nad tym ma podatnik.
4. Użyj IdWew w fakturach
IdWew wypełnia się tylko w szczególnych przypadkach, gdy na fakturze trzeba wskazać konkretny zakład, oddział lub jednostkę wewnętrzną (np. przy elemencie Podmiot3 w strukturze faktury, m.in. dla jednostek podrzędnych JST lub członków grupy VAT). Pole IDWew zapisuje się w fakturze XML zgodnie ze schematem FA(3) (aktualnie obowiązująca struktura logiczna od 1 lutego 2026). Dokumentacja XSD określa dokładne miejsce i format pola.
5. Zarządzaj IdWew w organizacji
Przechowuj mapowanie IdWew do jednostek i pracowników, sprawdzaj zgodność identyfikatora z wymaganym formatem (NIP-5cyfr) przed wysłaniem faktury do KSeF oraz aktualizuj dane przy zmianach w strukturze. Prawidłowe wdrożenie wymaga świadomego zaprojektowania uprawnień i ścisłego powiązania IdWew z procesami biznesowymi. Odpowiedzialność za poprawne przypisanie IdWew leży po stronie podatnika.
Najczęstsze problemy i rozwiązania
Jak nadać IdWew?
IdWew (InternalId) nie jest generowany automatycznie przez system. Podatnik samodzielnie ustala jego wartość, zachowując wymagany format NIP-5cyfr, i wskazuje go przy nadawaniu uprawnień administratorowi jednostki podrzędnej (endpoint POST /permissions/subunits/grants w KSeF API 2.0, wymagane uprawnienie SubunitManage). Po nadaniu można go zapisać w swoim systemie i używać przy wystawianiu faktur.
Jaki format musi mieć IdWew?
Format wynika ze schematu XSD faktury (typ TNIPIdWew): NIP podatnika (10 cyfr), myślnik, a następnie dokładnie 5 cyfr, np. 1234567890-00001. Nie jest to suma kontrolna wyliczana algorytmicznie z pozostałych cyfr - to stały wzorzec długości, który identyfikator musi spełniać.
Czy KSeF sprawdza poprawność IdWew?
KSeF weryfikuje zgodność IdWew z wymaganym formatem (NIP-5cyfr). Nie weryfikuje, czy IdWew jest przypisany do właściwej jednostki lub pracownika. Nadzór nad przypisaniami ma podatnik.
Czy mogę nadawać IdWew pracownikom?
Tak. IdWew można przypisywać pracownikom, oddziałom lub zakładom zgodnie z potrzebami organizacji. Dzięki temu w fakturach widać, która jednostka wewnętrzna jest odpowiedzialna za dany dokument. KSeF nie weryfikuje poprawności przypisań; odpowiedzialność leży po stronie podatnika.
Gdzie znajdę endpointy API do zarządzania IdWew?
Nadawanie uprawnień administratorowi jednostki podrzędnej z identyfikatorem InternalId (IdWew) odbywa się przez endpoint POST /permissions/subunits/grants w KSeF API 2.0 (wymagane uprawnienie SubunitManage). Pełna specyfikacja jest dostępna w dokumentacji OpenAPI KSeF API 2.0.
Po co jest IdWew i kiedy go stosować
W KSeF problem "kto widzi jakie faktury" ma charakter techniczno-prawny: system jest scentralizowany, a podstawowym identyfikatorem jest NIP. Bez IdWew osoby uprawnione do działania w imieniu podatnika mają potencjalnie dostęp do pełnego zasobu faktur. IdWew pozwala ograniczyć dostęp do faktur wybranych jednostek lub zwiększyć kontrolę nad zakupami. Stosowanie IdWew nie jest obowiązkowe; zależy od potrzeb organizacyjnych. Przydaje się zwłaszcza przy wielu oddziałach, zakładach, jednostkach podrzędnych (np. w JST) lub wewnętrznych centrach rozliczeń.
Struktura IdWew
IdWew to unikalny identyfikator zakładu, oddziału lub innej wyodrębnionej jednostki wewnętrznej podatnika (w dokumentacji KSeF API 2.0 nazywany InternalId). Zawiera NIP podatnika oraz dodatkowy ciąg znaków numerycznych. Format wynika ze schematu XSD faktury (typ TNIPIdWew): NIP (10 cyfr), myślnik, a następnie dokładnie 5 cyfr, np. 1111111111-33334 lub 1234567890-00001. To stały wzorzec formatu, a nie suma kontrolna wyliczana algorytmicznie z pozostałych cyfr. IdWew nie jest NIP-em i nie zastępuje NIP sprzedawcy ani nabywcy.
Nadawanie IdWew
IdWew nie jest generowany automatycznie przez system; wartość identyfikatora ustala samodzielnie podatnik, zachowując wymagany format NIP-5cyfr. Nadanie następuje przy przypisywaniu uprawnień administratorowi jednostki podrzędnej - przez endpoint POST /permissions/subunits/grants w KSeF API 2.0 (wymagane uprawnienie SubunitManage), gdzie IdWew wskazuje się jako contextIdentifier typu InternalId. Po nadaniu identyfikator można przepisać do własnego systemu i używać przy wystawianiu faktur. Podatnik decyduje, którym oddziałom, zakładom lub pracownikom przypisać dany IdWew.
Weryfikacja przez KSeF
KSeF sprawdza zgodność IdWew z wymaganym formatem (NIP-5cyfr). Nie weryfikuje, czy IdWew jest przypisany do właściwej jednostki lub pracownika. Niepoprawny format może skutkować odrzuceniem żądania lub faktury; zgodny z formatem identyfikator wystarczy do zaakceptowania. Odpowiedzialność za prawidłowe zarządzanie IdWew i przypisania leży po stronie podatnika.
Użycie IdWew na fakturze
Pole IdWew wypełnia się tylko w szczególnych przypadkach, gdy na fakturze wymagane jest wskazanie konkretnego zakładu, oddziału lub jednostki wewnętrznej (np. jednostki podrzędnej JST lub członka grupy VAT). W strukturze faktury KSeF (element Podmiot3) pole IDWew służy do wskazania wewnętrznego identyfikatora powiązanego z NIP. IdWew zapisuje się w fakturze XML zgodnie ze schematem FA(3) (aktualnie obowiązująca struktura logiczna od 1 lutego 2026). Szczegóły podaje dokumentacja XSD.
Zarządzanie IdWew w organizacji
W systemie firmy warto przechowywać mapowanie IdWew do jednostek wewnętrznych i pracowników, sprawdzać zgodność identyfikatorów z wymaganym formatem przed wysłaniem faktury do KSeF oraz aktualizować dane przy zmianach w strukturze. Prawidłowe wdrożenie wymaga zaprojektowania struktury uprawnień, poprawnego oznaczania faktur w strukturze FA(3) oraz powiązania identyfikatorów z procesami biznesowymi. KSeF nie sprawdza poprawności przypisań; nadzór należy do podatnika.
FAQ
Co to jest IdWew?
IdWew (identyfikator wewnętrzny jednostki) to unikalny identyfikator zakładu, oddziału lub innej wyodrębnionej jednostki wewnętrznej podatnika w KSeF. Składa się z NIP podatnika oraz ciągu znaków numerycznych (np. format 1234567890-00001). Służy do ograniczenia dostępu do faktur wybranych jednostek bez zakładania osobnych NIP. IdWew nie jest NIP-em i nie zastępuje NIP sprzedawcy ani nabywcy.
Czy IdWew jest obowiązkowy?
Nie. Stosowanie IdWew jest fakultatywne i zależy od potrzeb organizacyjnych podatnika. Warto go wprowadzić, gdy wiele oddziałów lub jednostek ma pracować tylko na swoich fakturach; dla małych firm często wystarczy model bez IdWew.
Jak nadać IdWew w KSeF?
IdWew (InternalId) nie jest generowany automatycznie przez system. Podatnik samodzielnie ustala jego wartość, zachowując wymagany format NIP-5cyfr, i wskazuje go przy nadawaniu uprawnień administratorowi jednostki podrzędnej (endpoint POST /permissions/subunits/grants w KSeF API 2.0). Po nadaniu można go zapisać w swoim systemie i uzupełniać na fakturach w szczególnych przypadkach (gdy wymagane jest wskazanie konkretnej jednostki wewnętrznej).
Czy mogę nadawać IdWew pracownikom?
Tak. IdWew można przypisywać pracownikom, oddziałom lub zakładom. Dzięki temu w fakturach widać, która jednostka wewnętrzna jest odpowiedzialna za dany dokument. KSeF nie weryfikuje przypisań; nadzór ma podatnik.
Czy KSeF sprawdza poprawność IdWew?
KSeF sprawdza zgodność IdWew z wymaganym formatem (NIP-5cyfr). Nie sprawdza, czy IdWew jest przypisany do właściwej jednostki lub pracownika. Odpowiedzialność za prawidłowe zarządzanie IdWew leży po stronie podatnika.
Gdzie znajdę endpointy API do zarządzania IdWew?
Nadawanie uprawnień administratorowi jednostki podrzędnej z identyfikatorem IdWew (InternalId) odbywa się przez endpoint POST /permissions/subunits/grants w KSeF API 2.0 (wymagane uprawnienie SubunitManage). Pełna specyfikacja jest dostępna w dokumentacji OpenAPI KSeF API 2.0.
Powiązane tematy
Przydatne serwisy
Status i komunikaty
API i narzędzia
Pierwsza grupa – status systemu KSeF i komunikaty techniczne Ministerstwa Finansów, druga – narzędzia do integracji z KSeF i walidacji faktur.