Autoryzacja podatnika

wskazówka

Jeśli pracujesz ze środowiskiem TEST należy pominąć ten krok. W środowisku testowym utworzenie podatnika powoduje automatyczne wygenerowanie certyfikatów. Próba pełnej autoryzacji nie powiedzie się.

Po dodaniu podatnika należy zautoryzować go w KSeF.

Obecnie KSeF Pipe umożliwia wykonanie tej operacji jedną metodą, tj. poprzez podpisanie dokumentu XML np. za pomocą profilu zaufanego, co jest najwygodniejszą techniką z punktu widzenia użytkownika końcowego. Idea jest taka, że użytkownik końcowy pobiera plik XML, po czym podpisuje go elektronicznie i odsyła. Jego podpis z tego dokumentu jest używany do wygenerowania certyfikatów w KSeF, które będą później używane do wszystkich operacji.

Generowanie pliku do podpisu

Aby wygenerować plik do podpisu wyślij następujące zapytanie do API:

POST /api/v1/taxpayers/:nipNumber/auth/signature/challenge

gdzie w miejsce :nipNumber podstaw NIP firmy, której dotyczy autoryzacja.

W odpowiedzi uzyskasz kod 201 oraz plik XML, który należy dać do pobrania i podpisania użytkownikowi końcowemu.

Odsyłanie podpisanego pliku

Po podpisaniu pliku wyślij następujące zapytanie do API:

POST /api/v1/taxpayers/:nipNumber/auth/signature/response

gdzie:

• w adresie, w miejsce :nipNumber podstaw NIP firmy, której dotyczy autoryzacja,
• w treści przekaż podpisany plik XML,
• pamiętaj o ustawieniu właściwego nagłówka Content-Type: application/xml.

wskazówka

Plik powinien zostać podpisany przez osobę, która ma przyznane uprawnienia dla danej firmy w KSeF.

• Dla jednoosobowych działalności gospodarczych jest to jej właściciel.
• Dla innych podmiotów należy najpierw zgłosić jedną osobę uprawnioną do KSeF do Urzędu Skarbowego za pomocą formularza ZAW-FA. Ta osoba może samodzielnie pracować z KSeF lub nadać kolejnym osobom uprawnienia w KSeF.

Plik może zostać podpisany za pomocą podpisu zaufanego, podpisu kwalifikowanego lub pieczęci kwalifikowanej, ale najbardziej powszechną metodą jest podpis zaufany.

Sprawdzanie statusu autoryzacji

Wysłanie podpisanego pliku rozpoczyna proces autoryzacji, który może chwilę potrwać. W celu sprawdzenia, czy autoryzacja się powiodła należy raz na jakiś czas (np. raz na kilka sekund) wysłać zapytanie do API:

GET /api/v1/taxpayers/:nipNumber/auth/certificate/info

gdzie w miejsce :nipNumber podstaw NIP firmy, której dotyczy autoryzacja.

Jeśli autoryzacja się powiodła, w odpowiedzi uzyskasz status 200 oraz dane wygenerowanego certyfikatu, np.

{
  "issuer": "G=Jan, SN=Kowalski, SERIALNUMBER=TINPL-5214137058, CN=Jan Kowalski, C=PL",
  "subject": "G=Jan, SN=Kowalski, SERIALNUMBER=TINPL-5214137058, CN=Jan Kowalski, C=PL",
  "notBefore": "2026-03-01T12:46:34+01:00",
  "notAfter": "2028-03-01T13:47:34+01:00",
  "serialNumber": "6096A81618DC742E",
  "publicKeyAlgorithm": "ECDSA"
}

Certyfikat zostanie wygenerowany na dane osoby, która podpisywała plik XML.

wskazówka

Jednym z powodów dla których certyfikat może nie zostać wygenerowany jest przekroczenie limitów. Jedna osoba posługując się swoim podpisem zaufanym lub kwalifikowanym (czyli przypisanym do jej PESEL) może w danym środowisku KSeF podpisać maksymalnie dwa certyfikaty.

W przypadku gdyby zaistniała konieczność wygenerowania większej liczby certyfikatów, należy skorzystać z pieczęci kwalifikowanej - czyli formy podpisu cyfrowego, który jest przypisany do firmy (a konkretnie jej NIP), a nie osoby (czyli PESEL). W przypadku użycia pieczęci limit wynosi 100 certyfikatów.

Testowanie autoryzacji

Na koniec opcionalnie możesz wywołać test, który spróbuje wykonać pełną procedurę autoryzacji w KSeF, uruchamiając ją w dokładnie taki sam sposób, jaki będzie używany przy realnych operacjach na fakturach. W tym celu wyślij następujące zapytanie do API:

POST /api/v1/taxpayers/:nipNumber/auth/test/perform

gdzie w miejsce :nipNumber podstaw NIP firmy, której dotyczy autoryzacja.

Jeśli test się powiedzie, w odpowiedzi uzyskasz status 200 oraz taką treść:

{
  "success": true
}