KSeF API - Integracja Systemu Faktur Elektronicznych z Odoo i Innymi ERP

Krajowy System e-Faktur (KSeF) to fundamentalna zmiana w polskim systemie podatkowym, która wprowadza obowiązek wystawiania i przesyłania faktur ustrukturyzowanych. Dla firm korzystających z systemów ERP jak Odoo, Sage czy Symfonia, integracja z KSeF staje się kluczowym elementem compliance. W tym artykule przedstawiamy techniczne aspekty integracji KSeF z systemami ERP.

Spis Treści

1. Czym jest KSeF i wymogi prawne
2. Struktura faktury ustrukturyzowanej
3. Autentykacja i bezpieczeństwo
4. Integracja KSeF z Odoo
5. Integracja z innymi systemami ERP
6. Obsługa błędów i walidacja
7. Najlepsze praktyki implementacji
8. FAQ

Czym jest KSeF i wymogi prawne

Krajowy System e-Faktur (KSeF) to system teleinformatyczny prowadzony przez Ministerstwo Finansów, służący do wystawiania, przesyłania i odbierania faktur ustrukturyzowanych. Od 1 stycznia 2026 roku KSeF staje się obowiązkowy dla wszystkich podatników VAT w Polsce.

Obowiązek dotyczy wystawiania faktur VAT w formie ustrukturyzowanej, przesyłania ich do KSeF przed wystawieniem odbiorcy oraz przechowywania kopii faktur w systemie przez okres wymagany przepisami.

Faktury ustrukturyzowane muszą zawierać wszystkie elementy wymagane przepisami VAT, w tym dane sprzedawcy i nabywcy, numery NIP, daty, numery faktur, szczegóły towarów i usług, stawki VAT oraz kwoty.

Struktura faktury ustrukturyzowanej

Faktura ustrukturyzowana to dokument XML zgodny ze schematem XSD udostępnionym przez Ministerstwo Finansów. Struktura obejmuje nagłówek z danymi faktury, sprzedawcę i nabywcę, pozycje faktury oraz podsumowanie.

Podstawowa struktura XML

    
        PLN
        2024-01-15
        2024-01-15
        FV/2024/01/001
    
    
        5251040828
        Przykład Sp. z o.o.
        
            PL
            mazowieckie
            warszawski
            Warszawa
            Przykładowa
            10
            5
            Warszawa
            00-001
        
    
    
        5261040828
        Nabywca Sp. z o.o.
        
            PL
            Kraków
            30-001
        
    
    
        
            1
            Usługa programistyczna
            usł.
            10
            100.00
            1000.00
            23
            230.00
        
    
    
        1000.00
        230.00
        1230.00
    

Autentykacja i bezpieczeństwo

Komunikacja z KSeF wymaga odpowiedniego uwierzytelnienia. System wykorzystuje uwierzytelnianie oparte na certyfikatach SSL oraz tokenach JWT.

Proces uwierzytelniania

Aby korzystać z KSeF, należy najpierw zarejestrować organizację w systemie i uzyskać dostęp produkcyjny. Komunikacja odbywa się przez REST API z wykorzystaniem protokołu TLS 1.2 lub wyższego.

import requests
import jwt
from datetime import datetime, timedelta

Generowanie tokena JWT
def generate_jwt_token(client_id, private_key_path):
    with open(private_key_path, 'r') as f:
        private_key = f.read()
    
    now = datetime.utcnow()
    payload = {
        'iss': client_id,
        'sub': client_id,
        'aud': 'ksef',
        'iat': now,
        'exp': now + timedelta(hours=1),
        'jti': f"{now.timestamp()}"
    }
    
    token = jwt.encode(payload, private_key, algorithm='RS256')
    return token

Wysłanie faktury do KSeF
def send_invoice_to_ksef(xml_content, token, environment='test'):
    base_url = 'https://api-ksef-test.mf.gov.pl' if environment == 'test' else 'https://api-ksef.mf.gov.pl'
    
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/xml'
    }
    
    response = requests.post(
        f'{base_url}/api/v1/invoices',
        data=xml_content,
        headers=headers
    )
    
    return response

Integracja KSeF z Odoo

Odoo może być zintegrowane z KSeF poprzez dedykowany moduł lub custom development. Poniżej przedstawiamy podejście programistyczne.

Tworzenie modułu KSeF dla Odoo

from odoo import models, fields, api
import xml.etree.ElementTree as ET
from datetime import datetime
import base64

class KSeFIntegration(models.Model):
    _name = 'ksef.integration'
    _description = 'KSeF Integration'
    
    name = fields.Char('Name')
    api_url = fields.Char('API URL', default='https://api-ksef.mf.gov.pl/api/v1')
    token = fields.Char('Access Token')
    active = fields.Boolean('Active', default=True)
    
    def generate_invoice_xml(self, invoice):
        """Generate KSeF compatible XML from invoice"""
        root = ET.Element('FAKTURA')
        root.set('xmlns', 'http://crd.gov.pl/wzor/2023/12/13/13192/')
        
        # Header
        header = ET.SubElement(root, 'FAKTURA')
        header.set('naglowek', datetime.now().isoformat())
        header.set('rodzaj', 'VAT')
        
        ET.SubElement(header, 'KODWaluty').text = 'PLN'
        ET.SubElement(header, 'dataWystawienia').text = invoice.date_invoice.strftime('%Y-%m-%d')
        ET.SubElement(header, 'numer').text = invoice.number
        
        # Seller
        seller = ET.SubElement(root, 'SPRZEDAWCA')
        ET.SubElement(seller, 'NIP').text = invoice.company_id.vat
        ET.SubElement(seller, 'PelnaNazwa').text = invoice.company_id.name
        
        # Buyer
        buyer = ET.SubElement(root, 'NABYWCA')
        if invoice.partner_id.vat:
            ET.SubElement(buyer, 'NIP').text = invoice.partner_id.vat
        ET.SubElement(buyer, 'PelnaNazwa').text = invoice.partner_id.name
        
        # Lines
        lines = ET.SubElement(root, 'POZYCJE')
        for idx, line in enumerate(invoice.invoice_line_ids):
            pos = ET.SubElement(lines, 'POZYCJA')
            ET.SubElement(pos, 'NrPorzadkowy').text = str(idx + 1)
            ET.SubElement(pos, 'NazwaTowaruUsługi').text = line.name
            ET.SubElement(pos, 'Ilosc').text = str(line.quantity)
            ET.SubElement(pos, 'CenaJednostkowa').text = str(line.price_unit)
            
        # Summary
        summary = ET.SubElement(root, 'PODSUMOWANIE')
        ET.SubElement(summary, 'WartoscNetto').text = str(invoice.amount_untaxed)
        ET.SubElement(summary, 'WartoscPodatku').text = str(invoice.amount_tax)
        ET.SubElement(summary, 'WartoscBrutto').text = str(invoice.amount_total)
        
        return ET.tostring(root, encoding='unicode')
    
    def send_to_ksef(self, invoice):
        """Send invoice to KSeF"""
        xml_content = self.generate_invoice_xml(invoice)
        
        # Call KSeF API
        headers = {
            'Authorization': f'Bearer {self.token}',
            'Content-Type': 'application/xml'
        }
        
        response = requests.post(
            f'{self.api_url}/invoices',
            data=xml_content,
            headers=headers
        )
        
        if response.status_code == 200:
            # Store KSeF reference
            invoice.write({'ksef_reference': response.json()['referenceNumber']})
            return True
        return False

Integracja z innymi systemami ERP

Sage

Sage posiada wbudowane funkcje KSeF w najnowszych wersjach. Dla starszych wersji, integracja realizowana jest przez API.

// Przykład integracji w C# dla Sage
public class KSeFConnector
{
    private string _apiUrl;
    private string _token;
    
    public void SendInvoice(SageInvoice invoice)
    {
        var xml = GenerateKSeFXML(invoice);
        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Bearer", _token);
        
        var response = client.PostAsync(
            $"{_apiUrl}/invoices",
            new StringContent(xml, Encoding.UTF8, "application/xml")
        ).Result;
    }
}

Symfonia

Symfonia oferuje moduł KSeF jako dodatek. Integracja programistyczna wymaga dostępu do bazy danych SQL.

Obsługa błędów i walidacja

KSeF zwraca szczegółowe kody błędów, które należy obsługiwać w systemie ERP.

Typowe kody błędów

Kody błędów obejmują: 100 - błąd autentykacji, 200 - nieprawidłowy format XML, 300 - brak wymaganego pola, 400 - nieprawidłowa wartość pola oraz 500 - błąd serwera KSeF.

def handle_ksef_response(response):
    if response.status_code == 200:
        return {'status': 'success', 'reference': response.json()['referenceNumber']}
    elif response.status_code == 400:
        errors = response.json()['errors']
        return {'status': 'error', 'errors': errors}
    elif response.status_code == 401:
        return {'status': 'error', 'message': 'Unauthorized - refresh token'}
    else:
        return {'status': 'error', 'message': 'Server error'}

Najlepsze praktyki implementacji

Walidacja przed wysłaniem

Zawsze waliduj fakturę lokalnie przed wysłaniem do KSeF. Sprawdź poprawność NIP, kompletność danych i zgodność ze schematem XSD.

Obsługa kolejek

Przy dużej liczbie faktur, zaimplementuj kolejkę przetwarzania, która wysyła faktury partiami i obsługuje błędy.

Retry i idempotentność

Zaimplementuj mechanizm ponawiania dla błędów sieciowych i upewnij się, że ponowne wysłanie tej samej faktury nie tworzy duplikatów.

Monitoring

Monitoruj status wysłanych faktur i alertuj o fakturach oczekujących dłużej niż określony czas.

Podsumowanie

Integracja KSeF z systemami ERP jest kluczowa dla compliance od 2026 roku. Odoo oferuje elastyczne możliwości integracji poprzez dedykowane moduły lub custom development. Podobne podeś

-cie stosuje się do innych systemów ERP jak Sage czy Symfonia.

Kluczowe aspekty to: walidacja faktur przed wysłaniem, obsługa błędów i retry, bezpieczne przechowywanie tokenów oraz monitoring statusu faktur w KSeF.

Powiązane Tematy

• KSeF i Odoo 19
• wdrożenie ERP
• automatyzacja finansów

FAQ