Bramka KSeF to aplikacja, która umożliwia przesyłanie i odbieranie faktur z Krajowego Systemu e-Faktur (KSeF) prowadzonego przez Ministerstwo Finansów.

Co warto wiedzieć już na początku

Bramka KSeF nie służy do wystawiania faktur. Jej zadaniem jest przesłanie do KSeF gotowego pliku XML z fakturą oraz pobieranie faktur, które otrzymujesz od kontrahentów.

Oznacza to, że fakturę najpierw przygotowujesz w swoim programie księgowym lub sprzedażowym (lub otrzymujesz ją z innej aplikacji), a Bramka KSeF zajmuje się jej bezpiecznym dostarczeniem do KSeF.

Kluczowa zasada: poprawny plik XML

Aplikacja działa na podstawie pliku XML, który został do niej dostarczony. Plik ten musi być zgodny z aktualną schemą KSeF opublikowaną przez Ministerstwo Finansów.

Jeśli przekażesz do Bramki KSeF plik XML, który nie spełnia wymagań schemy KSeF, faktura nie zostanie wysłana do KSeF.

Skąd pobrać aplikację?

Aplikację należy pobierać ze strony producenta: https://www.bramka-ksef.pl/pobierz

Na stronie pobierania wybierz wersję odpowiednią dla swojego systemu operacyjnego. Bramka KSeF dostępna jest w dwóch wersjach: Windows oraz macOS.

Wspierane wersje systemów operacyjnych

Nasze aplikacje wspierane są na systemach:

• Windows — od wersji Windows 10,
• macOS — od wersji Monterey.

Warto jednak pamiętać, że sam system operacyjny to nie wszystko. Na komfort i stabilność pracy istotny wpływ ma również specyfikacja techniczna urządzenia (m.in. procesor, pamięć RAM czy wydajność dysku). Odpowiednio dobrany sprzęt przekłada się bezpośrednio na płynność działania aplikacji i wygodę codziennej pracy.

Dodatkowo informujemy, że nie wspieramy urządzeń z macOS opartych na architekturze Intel. Aplikacja przeznaczona jest dla komputerów Apple z procesorami Apple Silicon (M1, M2, M3 i nowsze).

Instalacja na Windows

Pobierz plik instalacyjny ze strony producenta, uruchom go i postępuj zgodnie z instrukcjami kreatora instalacji. Po zakończeniu instalacji aplikacja jest gotowa do użycia.

Instalacja na macOS — uwaga!

Krok po kroku:

• Pobierz plik instalacyjny ze strony producenta.
• Otwórz pobrany plik — pojawi się okno instalatora z ikoną Bramki KSeF oraz skrótem do folderu Programy.
• Przeciągnij ikonę Bramki KSeF do folderu Programy.
• Zamknij okno instalatora.
• Uruchom aplikację z folderu Programy (np. przez Launchpad lub Finder).

Bramka KSeF nie aktualizuje się automatycznie. Aby korzystać z najnowszej wersji, musisz wykonać aktualizację samodzielnie. Procedura jest bardzo prosta i nie wymaga żadnej deinstalacji.

Jak zaktualizować Bramkę KSeF?

• Zamknij aplikację Bramka KSeF, jeśli jest uruchomiona. Aplikacja musi być wyłączona na czas aktualizacji.
• Wejdź na stronę producenta: https://www.bramka-ksef.pl/pobierz.
• Pobierz najnowszą wersję aplikacji odpowiednią dla swojego systemu operacyjnego.
• Uruchom pobrany plik instalacyjny — zastąpi on starą wersję nową.
• Uruchom aplikację — od teraz korzystasz z najnowszej wersji.

Nie odinstalowujesz starej wersji aplikacji. Aktualizacja polega po prostu na zastąpieniu starego pliku nowym. Wszystkie Twoje ustawienia i dane konfiguracyjne zostaną zachowane.

Po zainstalowaniu Bramka KSeF jest natychmiast gotowa do pracy. Zgodnie z zasadami licencji, aplikacja może być wykorzystywana całkowicie za darmo z limitem do 2 dokumentów miesięcznie.

Chcesz przetestować aplikację na większą skalę?

Jeśli przed zakupem chcesz przetestować aplikację, ale do testów potrzebujesz większego miesięcznego limitu dokumentów, skontaktuj się z BinSoft pod adresem kontakt@binsoft.pl. Udostępnimy Ci darmowy klucz licencyjny do testów.

Co zrobić, gdy potrzebujesz większego limitu?

Jeśli Twoja firma obsługuje większą liczbę dokumentów w miesiącu, należy zakupić licencję i zarejestrować aplikację kluczem licencyjnym. Licencję można zakupić za pośrednictwem naszego sklepu: sklep.binsoft.pl.

Jak działają limity dokumentów?

• Limity przyznawane są w trybie miesięcznym, natomiast opłata oraz sama licencja są roczne.
• Limity dotyczą miesiąca kalendarzowego — z początkiem każdego miesiąca licznik dokumentów rozpoczyna się od zera.
• Do jednego, wspólnego limitu wliczane są zarówno faktury wysyłane do KSeF, jak i odbierane z KSeF.

Dostępne miesięczne limity

• do 20 faktur miesięcznie
• do 60, 100, 200, 800, 1600 lub 3600 faktur miesięcznie
• BL — bez limitu
• BLU — bez limitu, wersja usługowa

Co oznacza wersja BLU (usługowa)?

W wariancie BLU Bramka KSeF działa jako usługa systemu Windows. Aplikacja jest instalowana na każdym komputerze osobno i pracuje jako niewidoczna usługa systemowa w tle. Nie trzeba uruchamiać żadnego okna — aplikacja działa automatycznie po włączeniu komputera.

Jak zarejestrować aplikację kluczem licencyjnym?

Z menu wybierz Pomoc → Rejestracja. W oknie rejestracji podaj dane swojej firmy oraz klucz licencyjny, który otrzymałeś po zakupie. Zatwierdź wprowadzone dane. Zamknij i ponownie uruchom aplikację. Dopiero po restarcie programu zmiany zostaną zastosowane, a nowy limit dokumentów stanie się aktywny.

Po upływie okresu ważności licencji nie musisz prosić o nowy klucz licencyjny. Przedłużenie licencji nie wymaga nowego klucza ani ponownej rejestracji aplikacji.

Jak to działa?

• Po dokonaniu przedłużenia licencji zmienia się jej ważność, ale brzmienie klucza pozostaje takie samo.
• Twój dotychczasowy klucz licencyjny po przedłużeniu nadal działa — po prostu otrzymujesz nowy, dłuższy okres ważności.
• Nie musisz ponownie wprowadzać klucza ani ponownie rejestrować aplikacji — wszystko działa dalej tak, jak dotychczas.

Aby Bramka KSeF mogła komunikować się z Krajowym Systemem e-Faktur w imieniu Twojej firmy, musisz najpierw przeprowadzić proces uwierzytelnienia.

Otwórz ustawienia

Na macOS: z górnego menu wybierz Bramka KSeF → Ustawienia. Na Windows: z menu Start w aplikacji wybierz Ustawienia. Pojawi się okno konfiguracji z zakładkami u góry. Wybierz zakładkę KSeF, a następnie podzakładkę Główna.

Krok 1. Konfiguracja podstawowa (zakładka Główna)

• Zaznacz opcję Włącz obsługę Krajowego Systemu e-Faktur (KSeF).
• Wybierz wersję KSeF — aktualnie jest to KSeF 2.0.
• Wybierz środowisko: produkcyjne.
• Podaj numer NIP swojej firmy i kliknij Zapisz.

Krok 2. Wybór metody uwierzytelniania (zakładka Uwierzytelnianie)

Przejdź do dolnej zakładki Uwierzytelnianie. Możesz uwierzytelnić się w KSeF jedną z dwóch metod.

Metoda A — uwierzytelnienie wprost z programu

Kliknij Uwierzytelnij się. Aplikacja przygotuje plik żądania autoryzacyjnego — pobierz go i zapisz na dysku. Następnie podpisz ten plik podpisem kwalifikowanym, pieczęcią firmową lub profilem zaufanym. Po podpisaniu wróć do aplikacji i w sekcji Kontynuuj uwierzytelnianie wskaż podpisany plik. Aplikacja dokończy proces.

Metoda B — istniejący certyfikat z innego systemu

Jeśli posiadasz już certyfikat wygenerowany w innym systemie (np. w Aplikacji Ministerstwa Finansów), możesz z niego skorzystać. Potrzebne będą: plik z certyfikatem (rozszerzenie .cert), plik z kluczem prywatnym (rozszerzenie .key) oraz hasło (15-znakowy ciąg liter, cyfr i znaków specjalnych). Wskaż w aplikacji wymagane pliki, wpisz hasło i kliknij Zapisz.

Krok 3. Certyfikaty (zakładka Certyfikaty)

Przejdź do zakładki Certyfikaty. Znajdziesz tutaj listę wszystkich swoich certyfikatów. Aby wygenerować nowy certyfikat — np. do automatycznego uwierzytelniania lub do obsługi faktur offline — kliknij Wygeneruj, wskaż rodzaj certyfikatu, podaj nazwę i kliknij Zapisz.

Krok 4. Powrót do zakładki Główna

Po wygenerowaniu certyfikatu wróć do dolnej zakładki Główna. W polu Automatyczne uwierzytelnianie wskaż utworzony wcześniej certyfikat. Jeśli chcesz obsługiwać także certyfikaty offline, wskaż odpowiedni certyfikat w polu Certyfikat offline. W sekcji Eksport faktur zaznacz opcję Eksportuj faktury do systemu KSeF, a jeśli chcesz obsługiwać faktury offline — dodatkowo zaznacz Twórz faktury offline z faktur do wysyłki. Kliknij Zapisz.

Bramka KSeF może automatycznie pobierać faktury, które wystawili Tobie Twoi kontrahenci i które trafiły do Krajowego Systemu e-Faktur. Tę funkcję włączasz w ustawieniach.

Jak włączyć automatyczne pobieranie faktur?

Przejdź do Ustawienia → KSeF → Główna. Zaznacz opcję Automatycznie importuj faktury otrzymane z KSeF. W polu Data początkowa wskaż datę, od kiedy ma się rozpocząć import. Kliknij Zapisz.

Dlaczego data początkowa może się zmienić?

Gdy ponownie wejdziesz do ustawień, możesz zauważyć, że data w polu „Data początkowa" uległa zmianie. To prawidłowe działanie aplikacji. Aplikacja wskazuje datę, od której rozpocznie kolejne przeszukiwanie bazy KSeF. Każde nowe sprawdzenie startuje od momentu, do którego aplikacja doszła w poprzednim cyklu. Dzięki temu nie pobiera wkółko tych samych faktur.

Sposób wysyłki faktur zależy od tego, jak korzystasz z Bramki KSeF.

Wariant 1. Bramka KSeF działa samodzielnie

Jeśli używasz Bramki KSeF jako samodzielnej aplikacji, otwórz okno główne i przeciągnij plik (lub pliki) XML z fakturami do okna głównego aplikacji — Bramka KSeF rozpozna je automatycznie i wyśle do KSeF. Możesz również użyć przycisku Wyślij faktury, aby ręcznie zainicjować wysyłkę.

Wariant 2. Bramka KSeF zintegrowana z zewnętrznym programem

Jeśli Bramka KSeF jest zintegrowana z innym programem (np. z Twoim systemem sprzedażowym lub księgowym), wysyłka odbywa się automatycznie — bez konieczności ręcznego przeciągania plików. W takim przypadku czas wysyłki faktur do KSeF zależy od konfiguracji integracji ustawionej w Twoim systemie zewnętrznym.

Po uruchomieniu Bramki KSeF zobaczysz okno główne aplikacji. Składa się ono z kilku przejrzystych sekcji.

Sekcja KSeF

• Synchronizuj — wymusza natychmiastową synchronizację aplikacji z KSeF (sprawdzenie statusu wysłanych dokumentów, pobranie nowych itd.).
• Wyślij faktury — ręczne uruchomienie wysyłki dokumentów oczekujących w kolejce do KSeF.
• Odbierz faktury — pobranie z KSeF faktur otrzymanych od kontrahentów.

Sekcja Rejestr dokumentów

• Odebrane — lista faktur, które otrzymałeś od swoich kontrahentów (faktury zakupowe).
• Wysłane — lista faktur, które Twoja firma wystawiła i wysłała do KSeF (faktury sprzedażowe).

Sekcja Logi

W dolnej części okna znajduje się panel Logi — dziennik zdarzeń aplikacji. Logi przydają się przy diagnozowaniu problemów oraz przy kontakcie z pomocą techniczną.

Pasek tytułowy

W górnej części okna widoczna jest nazwa aplikacji wraz z numerem wersji (np. „Bramka KSeF v26.1.12"). Numer wersji warto znać — będziesz go potrzebować przy kontakcie z pomocą techniczną.

Rejestr dokumentów to miejsce, w którym możesz przejrzeć wszystkie faktury obsłużone przez Bramkę KSeF.

Jak otworzyć rejestr?

Rejestr otwiera się z menu KSeF, gdzie znajdziesz dwie opcje: Faktury wysłane oraz Faktury odebrane. Możesz również dotrzeć do rejestru klikając w okno główne aplikacji w przyciski Wysłane lub Odebrane w sekcji Rejestr dokumentów.

Co znajdziesz w rejestrze?

Dla każdego dokumentu rejestr pokazuje m.in. numer dokumentu, datę wystawienia, status (np. zaakceptowana przez KSeF, odrzucona, oczekuje na weryfikację), numer referencyjny KSeF, numer KSeF nadany dokumentowi oraz ewentualne komunikaty o błędach. Dzięki rejestrowi możesz w każdej chwili sprawdzić, co dzieje się z konkretną fakturą.

Pierwsze kroki

Czy mogę przetestować program Bramka KSeF?

Tak. Bramka KSeF jest dostępna do pobrania ze strony https://www.bramka-ksef.pl/pobierz i może być używana bezpłatnie z limitem do 2 dokumentów miesięcznie. Jeśli do przetestowania aplikacji potrzebujesz większego limitu, skontaktuj się z BinSoft pod adresem kontakt@binsoft.pl — udostępnimy Ci darmowy klucz licencyjny do testów.

Na jakich systemach operacyjnych działają aplikacje BinSoft?

Aplikacje BinSoft wspierane są na systemach Windows (od wersji Windows 10) oraz macOS (od wersji Monterey, wyłącznie urządzenia z procesorami Apple Silicon; nie wspieramy macOS na architekturze Intel).

Jak sprawdzić, której wersji aplikacji używam?

Numer wersji widoczny jest w pasku tytułowym okna głównego aplikacji (np. „Bramka KSeF v26.1.12").

Licencja i rejestracja

Jak zarejestrować program kluczem licencyjnym?

Z menu wybierz Pomoc → Rejestracja. W oknie podaj dane firmy oraz klucz licencyjny. Po zatwierdzeniu zamknij i ponownie uruchom aplikację — dopiero po restarcie zmiany staną się aktywne.

Czy moja licencja wygasa? Co wtedy?

Licencje są ważne przez określony czas. Po jego upływie należy przedłużyć licencję u producenta lub partnera. Przedłużenie nie wymaga nowego klucza — Twój dotychczasowy klucz zyskuje dłuższy okres ważności.

Uwierzytelnianie

Skąd wziąć token autoryzacyjny?

Token autoryzacyjny wygenerujesz w Aplikacji Podatnika KSeF udostępnionej przez Ministerstwo Finansów: Aplikacja Podatnika KSeF.

Jak naprawić błąd uwierzytelniania KSeF: „login.signedXml"?

Jednorazowe niepowodzenie uwierzytelnienia zdarza się z przyczyn technicznych po stronie serwera KSeF. Spróbuj ponownie. Jeśli problem się powtarza, sprawdź: ważność certyfikatu, poprawność jego instalacji, zgodność NIP na certyfikacie z NIP firmy, wybrane środowisko (produkcyjne, nie testowe), ustawienia KSeF w programie. Upewnij się również, że program jest zaktualizowany do najnowszej wersji.

Dlaczego pojawia się „Upłynął czas logowania w KSeF"?

Sesje w KSeF są ważne przez ograniczony czas — po upływie tego czasu każda kolejna operacja wymaga ponownego uwierzytelnienia. Wejdź w Ustawienia → KSeF → Uwierzytelnianie i przeprowadź proces ponownie. Aby uniknąć częstego logowania, skonfiguruj automatyczne uwierzytelnianie certyfikatem.

Wysyłka faktur

Co zrobić, gdy faktura została odrzucona z błędem „nieprawidłowy XML"?

Błąd oznacza, że plik faktury nie jest zgodny ze schemą wymaganą przez KSeF. Bramka KSeF jedynie przesyła plik — nie zmienia jego treści. Sprawdź w swoim systemie sprzedażowym lub księgowym, czy plik XML generowany jest zgodnie z aktualną schemą KSeF, lub skontaktuj się z producentem tego systemu.

Czy mogę hurtowo wysyłać faktury do KSeF?

Tak. Bramka KSeF obsługuje wysyłkę wielu faktur jednocześnie. Możesz przeciągnąć kilka plików XML naraz do okna głównego, skonfigurować monitorowanie folderu albo skorzystać z integracji z systemem zewnętrznym.

Czy istnieje możliwość wysłania do KSeF faktury wystawionej online?

Tak — pod warunkiem, że system online pozwala pobrać fakturę w postaci pliku XML zgodnego ze schemą KSeF. Jeśli Twoje narzędzie online nie eksportuje plików XML w formacie KSeF, niestety nie będziesz mógł wysłać faktur za pośrednictwem Bramki KSeF.

Co oznacza błąd transportu HTTP (12175) w KSeF?

Błąd HTTP 12175 oznacza problem z komunikacją z serwerem KSeF. Najczęstsze przyczyny: tymczasowa niedostępność serwera KSeF po stronie Ministerstwa Finansów, blokowanie połączenia przez program antywirusowy lub zaporę sieciową, problemy z połączeniem internetowym. Poczekaj kilka minut i spróbuj ponownie. Jeśli problem się powtarza, sprawdź ustawienia zapory sieciowej i antywirusa.

Co zrobić, kiedy wyczerpie mi się miesięczny limit dokumentów?

Skontaktuj się z BinSoft (kontakt@binsoft.pl) lub ze swoim Partnerem w celu zwiększenia (upgrade'u) miesięcznego limitu dokumentów. Po dokonaniu zmiany licencja zostanie odpowiednio rozszerzona, a aplikacja będzie mogła ponownie wysyłać i odbierać dokumenty bez przerwy w pracy.

Pobieranie faktur

Dlaczego nie mogę zaimportować faktur z KSeF?

Najczęstsze przyczyny: wyłączony import (sprawdź, czy w ustawieniach jest zaznaczona opcja „Automatycznie importuj faktury otrzymane z KSeF"), brak uwierzytelnienia (sesja w KSeF mogła wygasnąć), niewłaściwa data początkowa, problemy z połączeniem, brak faktur w wybranym okresie. Jeśli żaden z punktów nie pomaga, sprawdź logi aplikacji w oknie głównym.

Dlaczego „data początkowa" ulega zmianie?

To prawidłowe działanie aplikacji. Po zapisaniu ustawień Bramka KSeF zaczyna cyklicznie sprawdzać KSeF w poszukiwaniu nowych faktur. Wartość w polu „Data początkowa" pokazuje datę, od której rozpocznie się kolejne przeszukiwanie. Dzięki temu aplikacja nie pobiera w kółko tych samych faktur i nie tworzy duplikatów.

Integracja i programiści

Z jakimi programami współpracuje Bramka KSeF?

Bramka KSeF współpracuje z dowolnym programem, który generuje faktury w pliku XML zgodnym ze schemą KSeF. Nie jesteś przywiązany do jednego dostawcy oprogramowania — wystarczy, że Twój system księgowy lub sprzedażowy potrafi wyeksportować fakturę w odpowiednim formacie.

Czy mogę zintegrować Bramkę KSeF ze swoją aplikacją?

Tak. Bramka KSeF oferuje kilka sposobów integracji: przez TCP/IP, WebSocket, lokalny serwer HTTP/HTTPS, współdzielony folder lokalny, folder na serwerze FTP/SFTP lub bramę BinSoft Gate. Szczegóły w dokumentacji dla programistów — kontakt: kontakt@binsoft.pl.

Czy dostępna jest dokumentacja dla programistów?

Tak. BinSoft udostępnia szczegółową dokumentację techniczną — kontakt: kontakt@binsoft.pl.

Bezpieczeństwo i połączenia

Czy aplikacja działa bez połączenia z internetem?

Sama komunikacja z KSeF wymaga internetu. Bramka KSeF obsługuje jednak również faktury offline — możesz włączyć tę funkcję w ustawieniach.

Czy moje dane są bezpieczne?

Tak. Komunikacja z KSeF odbywa się przy użyciu szyfrowanego połączenia oraz certyfikatu autoryzacyjnego. Tylko Twoja firma (po uwierzytelnieniu) ma dostęp do operacji wykonywanych w jej imieniu w KSeF.

W przypadku jakichkolwiek problemów z aplikacją lub dodatkowych pytań, skontaktuj się z naszą pomocą techniczną pisząc na adres: pomoc@binsoft.pl.

Pozostałe kontakty: ogólny kontakt@binsoft.pl, strona aplikacji www.bramka-ksef.pl, strona producenta www.binsoft.pl, sklep sklep.binsoft.pl.