Dokumentacja integracyjna Bramki KSeF (black-box)
dla Krajowego Systemu e-Faktur (KSeF 2.0)

Uwaga! W ramach komponentu Bramka KSeF (black-box) dostarczane są operacje opisane w niniejszym rozdziale, które są dedykowane dla komponentu oraz wszystkie operacje opisane w rozdziale KSEF REST API. Firma decydująca się na integrację swojego systemu z wykorzystaniem Bramki KSeF (black-box) samodzielnie decyduje co do sposobu wykorzystania poszczególnych operacji.

Komponenty

Na potrzeby niniejszej dokumentacji zostały przyjęte 3 podstawowe komponenty, które uczestniczą w procesach biznesowych związanych z obsługą zarządzania fakturami KSeF z wykorzystaniem Bramki KSeF:

Diagram: Komponenty

System wywołujący

System informatyczny Klienta, który komunikuje się z KSeF 2.0 za pośrednictwem wdrożonej on-premise (lokalnie u klienta) Bramki KSeF (black-box).

Krajowy System e-Faktur (KSeF 2.0)

Krajowy System e-Faktur jest centralnym repozytorium ustrukturyzowanych faktur elektronicznych, które jest zarządzane i utrzymywany przez Ministerstwo Finansów.

Bramka KSeF (black-box)

Komponent techniczny implementowany w architekturze Docker lub jako VM (wirtualna maszyna), realizujący podstawowe funkcjonalności związane z wysyłką faktur do KSeF. Bramka KSeF (black-box) jest wdrażana i utrzymywana w infrastrukturze Klienta.

Operacje

Rozdział zawiera opis dostępnych w ramach Bramki KSeF (black-box) operacji.

Diagram: Interfejs dla Bramki KSeF (black-box) wraz z dostępnymi metodami

boxUploadInvoice

Metoda umożliwia wysłanie pojedynczej faktury do KSeF. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: boxUploadInvoice

BoxUploadInvoiceRequest

Klasa została opisana w rozdziale BoxUploadInvoiceRequest.

BoxUploadInvoiceResponse

Klasa reprezentuje odpowiedź informującą o statusie wysłanej do Bramki KSeF (black-box) faktury.

result : boolean – Wartość atrybutu true, informuje o poprawnym otrzymaniu całej paczki faktur przez Bramkę KSeF (black-box).

boxUploadInvoiceStatus

Metoda umożliwia sprawdzenie statusu pojedynczej faktury wysłanej do KSeF. Kliknij w nazwę operacji, aby przejść do Swagger UI.

 

Diagram: boxUploadInvoiceStatus

UploadId

Klasa została opisana w rozdziale UploadId.

BoxUploadInvoiceStatusResponse

Klasa reprezentuje odpowiedź informującą o statusie wysłanej do KSeF faktury.

uploadId : string – Unikalny identyfikator przesyłanej faktury.

invoiceInfo : InvoiceInfo – Atrybut zawiera tablice z informacjami szczegółowo opisującymi status wysłanych faktur. Ten typ złożony został opisany w rozdziale InvoiceInfo.

boxUploadBatch

Metoda umożliwia wysłanie paczki faktury do KSeF. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: boxUploadBatch

BoxUploadBatchRequest

Klasa została opisana w rozdziale BoxUploadBatchRequest.

BoxUploadBatchResponse

Klasa reprezentuje odpowiedź informującą o statusie wysłanej do Bramki KSeF (black-box) paczki faktur.

result : boolean – Wartość atrybutu true, informuje o poprawnym otrzymaniu całej paczki faktur przez Bramkę KSeF (black-box).

boxUploadBatchStatus

Metoda umożliwia sprawdzenie statusu paczki faktur wysłanych do KSeF. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: boxUploadBatchStatus

UploadId

Klasa została opisana w rozdziale UploadId.

BoxUploadBatchStatusResponse

Klasa reprezentuje odpowiedź informującą o statusie wysłanych do KSeF faktur.

uploadId : string – Unikalny identyfikator przesyłanej paczki faktur.

invoiceInfo : InvoiceInfo – Atrybut zawiera tablice z informacjami szczegółowo opisującymi status wysłanych faktur. Ten typ złożony został opisany w rozdziale InvoiceInfo.

boxDownloadInvoices

Metoda umożliwia zdefiniowanie i wysłanie do KSeF kryteriów wyszukiwania dla których zwrócone zostaną znalezione faktury. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: boxDownloadInvoices

BoxDownloadInvoicesRequest

Klasa została opisana w rozdziale BoxDownloadInvoicesRequest.

BoxDownloadInvoicesResponse

Klasa reprezentuje odpowiedz informującą o statusie przesłanego zapytania do KSeF.

result : boolean – Wartość atrybutu true, informuje o poprawnym przekazaniu do Bramki KSeF (black-box) żądania wyszukiwania faktur KSeF.

boxDownloadInvoicesResult

Metoda umożliwia pobranie z KSeF wszystkich znalezionych faktur, spełniających kryteria wyszukiwania zdefiniowane w żądaniu BoxDownloadInvoicesRequest. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: boxDownloadInvoicesResult

DownloadId

Klasa została opisana w rozdziale DownloadId.

ApplicationZipContent

Klasa została opisana w rozdziale ApplicationZipContent.

Parametry

Rozdział zawiera zestawienie wszystkich parametrów w podziale na typ:

• path – parametr przekazywany w ścieżce URL
• requestBody – parametr przekazywany w treści żądania

Path

Parametry wywołania operacji zawarte w ścieżce (path).

UploadId

Klasa reprezentuje przesyły identyfikator faktury lub paczki faktur

uploadId : string – Unikalny identyfikator przesyłanej faktury lub paczki faktur.

DownloadId

Klasa reprezentuje przesyły identyfikator wyszukiwania faktur.

downloadId : string – Unikalny identyfikator wyszukiwania faktur, generowany podczas wysyłania żądania BoxDownloadInvoicesRequest, a wykorzystywany jako parametr wejściowy w operacji boxDownloadInvoicesResult.

RequestBody

Paramtery typu requestBody przekazywane w treści żądania.

BoxUploadInvoiceRequest

Klasa opisuje dane niezbędne do wysłania faktury ustrukturyzowanej do KSeF.

uploadId : string – Identyfikator przesyłanej faktury.

offline : boolean – Wartość true atrybutu oznacza, że przesyłana jest faktura wygenerowana w trybie offline24.

notify : boolean – Wartość true atrybutu oznacza, że użytkownik zdefiniował w panelu użytkownika webhook, na który system ma wysłać informacje w przypadku pojawienia się w KSeF informacji o statusie wysłanych faktur.

invoiceData : string – Wysyłana faktura zgodna z obowiązującą schemą FA(2) lub FA(3), zakodowana z wykorzystaniem Base64.

BoxUploadBatchRequest

Klasa opisuje dane niezbędne do wysłania całej paczki faktur ustrukturyzowanych do KSeF.

uploadId : string – Identyfikator przesyłanej faktury.

offline : boolean – Wartość true atrybutu oznacza, że przesyłana jest faktura wygenerowana w trybie offline24.

notify : boolean – Wartość true atrybutu oznacza, że użytkownik zdefiniował w panelu użytkownika webhook, na który system ma wysłać informacje w przypadku pojawienia się w KSeF informacji o statusie wysłanych faktur.

invoiceVersion : KsefInvoiceVersion – Atrybut zawiera informacje o schemie wysyłanych faktur. Wszystkie faktury muszą być tej samej schemy. Typ zawartości został opisany w rozdziale KsefInvoiceVersion.

BoxDownloadInvoicesRequest

Klasa reprezentuje żądanie pozwalające na zdefiniowanie parametrów wyszukiwania faktur w KSeF.

downloadId : string – Wygenerowany unikalny identyfikator wyszukiwania, po którym w metodzie boxDownloadInvoicesResult możliwe pobranie znalezionych faktur.

notify : boolean – Wartość true atrybutu oznacza, że użytkownik zdefiniował w panelu użytkownika webhook, na który system ma wysłać informacje w przypadku pojawienia się w KSeF informacji o statusie wysłanych faktur.

subjectType : SubjectType – Określenie jakiego typu faktury wyszukujemy. Typ zawartości opisany w rozdziale SubjectType.

range : KsefInvoiceQueryStartRange – Wybór okresu dla jakiego mają zostać wyszukane faktury. Typ zawartości opisany w rozdziale KsefInvoiceQueryStartRange.