KSeF API - Jak Zintegrować System z Krajowym Systemem e-Faktur

Integracja z KSeF API to kluczowy element automatyzacji procesu fakturowania. W tym przewodniku pokażemy krok po kroku, jak połączyć się z API KSeF, jakie endpointy są dostępne i jak wysłać pierwszą fakturę programistycznie.

Spis treści

• Wymagania techniczne
• Autentykacja w API KSeF
• Główne endpointy API
• Przykład wysyłki faktury w Python
• Obsługa błędów
• Środowisko testowe
• FAQ

Wymagania techniczne

Token autoryzacyjny

Aby korzystać z API KSeF, potrzebujesz tokenu autoryzacyjnego. Token uzyskasz przez:

1. Zalogowanie się do aplikacji webowej KSeF
2. Przejście do sekcji "Integracje" lub "API"
3. Wygenerowanie nowego tokenu
4. Token jest ważny 90 dni, po czym należy go odświeżyć

Podpis kwalifikowany lub pieczęć

Dla niektórych operacji (np. masowe wysyłki) wymagany jest podpis kwalifikowany lub pieczęć elektroniczna.

Środowisko

• Produkcja: https://ksef.mf.gov.pl
• Testowe: https://ksef-test.mf.gov.pl

Autentykacja w API KSeF

Token Bearer

API KSeF używa autentykacji Bearer Token. W nagłówku HTTP musisz przesłać:

Authorization: Bearer TWÓJ_TOKEN

Przykład w Python

import requests

TOKEN = "twój_token_ksef"
BASE_URL = "https://ksef.mf.gov.pl/api"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# Sprawdź status API
response = requests.get(f"{BASE_URL}/status", headers=headers)
print(response.json())

Główne endpointy API

Wysyłka faktury

POST /api/faktury/wyslij

Wysyła fakturę do KSeF. Wymaga XML w body.

Odbiór faktury

GET /api/faktury/odbierz/{nrKSeF}

Pobiera fakturę o podanym numerze KSeF.

Lista faktur

GET /api/faktury/lista?dataOd=2026-01-01&dataDo=2026-01-31

Zwraca listę faktur z danego okresu.

Status faktury

GET /api/faktury/status/{nrKSeF}

Sprawdza status przetworzenia faktury.

Przykład wysyłki faktury w Python

import requests
import xml.etree.ElementTree as ET

# Dane autoryzacyjne
TOKEN = "twój_token"
BASE_URL = "https://ksef.mf.gov.pl/api"

# Przygotuj XML faktury
faktura_xml = """<?xml version="1.0" encoding="UTF-8"?>
<Faktura xmlns="http://crd.gov.pl/wzor/2023/12/13/12648/">
    <Naglowek>
        <KodFormularza>FA (1)</KodFormularza>
        <WariantFormularza>1</WariantFormularza>
    </Naglowek>
    <!-- ... reszta faktury ... -->
</Faktura>"""

# Wyślij fakturę
headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/xml"
}

response = requests.post(
    f"{BASE_URL}/faktury/wyslij",
    data=faktura_xml.encode('utf-8'),
    headers=headers
)

if response.status_code == 200:
    result = response.json()
    print(f"Faktura wysłana! Nr KSeF: {result['nrKSeF']}")
    print(f"UPO: {result['upo']}")
else:
    print(f"Błąd: {response.status_code}")
    print(response.text)

Obsługa błędów

Typowe kody błędów

• 400 - Nieprawidłowe żądanie (błąd w XML)
• 401 - Brak autoryzacji (nieprawidłowy token)
• 404 - Faktura nie istnieje
• 409 - Konflikt (faktura o tym numerze już istnieje)
• 500 - Błąd serwera KSeF

Retry logic

import time

def send_with_retry(xml_data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, data=xml_data, headers=headers)
            if response.status_code == 200:
                return response
            elif response.status_code == 500:
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            else:
                raise Exception(f"Błąd: {response.status_code}")
        except requests.exceptions.RequestException:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    
    raise Exception("Przekroczono liczbę prób")

Środowisko testowe

Zalecamy rozpoczęcie od środowiska testowego:

1. Zarejestruj się na ksef-test.mf.gov.pl
2. Wygeneruj token testowy
3. Przetestuj wszystkie operacje
4. Po pomyślnych testach przejdź na produkcję

FAQ

Ostatnia aktualizacja: marzec 2026 | Autor: WorkToGrow - Eksperci KSeF