KSeF API - Jak Zintegrować System z Krajowym e-Fakturowaniem

Integracja z KSeF przez API to najbardziej efektywny sposób na automatyzację wymiany faktur z Ministerstwem Finansów. W tym przewodniku pokażemy krok po kroku, jak połączyć swój system z KSeF API.

Spis treści

• Wymagania techniczne
• Autentykacja w API KSeF
• Główne endpointy API
• Wysyłanie faktury
• Pobieranie faktur
• Obsługa błędów
• FAQ

Wymagania techniczne

Przed rozpoczęciem integracji upewnij się, że masz:

• Token autoryzacyjny - wygenerowany w aplikacji KSeF
• Podpis kwalifikowany lub pieczęć elektroniczną
• Środowisko testowe (sandbox) - do testowania integracji
• Środowisko produkcyjne - do właściwej pracy

Środowiska KSeF

Autentykacja w API KSeF

KSeF API używa autentykacji opartej na tokenie. Token jest ważny przez 24 godziny.

Generowanie tokena

POST /api/v1/auth/token
Content-Type: application/json

{
  "nip": "1234567890",
  "signature": "base64_encoded_signature"
}

Użycie tokena

GET /api/v1/invoices
Authorization: Bearer {token}

Główne endpointy API

Wysyłanie faktur

POST /api/v1/invoices

Pobieranie faktur

GET /api/v1/invoices/{ksefNumber}

Sprawdzanie statusu

GET /api/v1/invoices/{ksefNumber}/status

Pobieranie UPO

GET /api/v1/invoices/{ksefNumber}/upo

Wysyłanie faktury

Przykład w Python

import requests
import xml.etree.ElementTree as ET

# Konfiguracja
KSEF_URL = "https://ksef-test.mf.gov.pl/api/v1"
TOKEN = "twój_token"

# Wczytaj fakturę XML
with open('faktura.xml', 'rb') as f:
    invoice_xml = f.read()

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

response = requests.post(
    f'{KSEF_URL}/invoices',
    headers=headers,
    data=invoice_xml
)

if response.status_code == 200:
    result = response.json()
    print(f"Faktura wysłana. Numer KSeF: {result['ksefNumber']}")
else:
    print(f"Błąd: {response.status_code} - {response.text}")

Pobieranie faktur

Pobieranie faktur przychodzących

# Pobierz listę faktur
response = requests.get(
    f'{KSEF_URL}/invoices/incoming',
    headers={'Authorization': f'Bearer {TOKEN}'},
    params={'dateFrom': '2026-01-01', 'dateTo': '2026-01-31'}
)

invoices = response.json()
for invoice in invoices:
    print(f"{invoice['ksefNumber']}: {invoice['buyerName']}")

Obsługa błędów

Kody błędów HTTP

FAQ

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