KSeF API – jak wysłać fakturę do KSeF?

Pytanie „jak wysłać fakturę do KSeF przez API" wydaje się proste, dopóki nie zacznie się je realizować w praktyce — bo samo „wysłanie" to tylko jeden z kilku kroków, które muszą zajść poprawnie, żeby dokument został przyjęty i uzyskał numer KSeF. Poniżej rozkładamy ten proces na konkretne etapy.

Zanim wyślesz — czego potrzebujesz

• Dane faktury — sprzedawca, nabywca, pozycje, stawki VAT, sposób płatności, w komplecie i bez braków.
• Uwierzytelnienie — poprawnie skonfigurowany certyfikat, token lub inny mechanizm autoryzacji, zgodny z kontekstem podmiotu wysyłającego dokument (szerzej w artykule o autoryzacji).
• Środowisko docelowe — na etapie testów zawsze środowisko TEST, nigdy produkcyjne.

Krok 1 — przygotowanie dokumentu FA(3)

Dane faktury muszą zostać przekształcone w dokument XML zgodny ze schematem logicznym FA(3) — z zachowaniem wymaganej struktury, kolejności elementów i formatu poszczególnych pól. To ten etap generuje najwięcej błędów walidacyjnych, jeśli robiony jest ręcznie, bez dokładnej znajomości schematu XSD. Warstwy pośredniczące (jak API KSeFService) pozwalają pominąć ręczne budowanie XML — wystarczy przekazać dane w prostszym formacie (np. JSON), a poprawny dokument generowany jest automatycznie.

Krok 2 — walidacja przed wysyłką

Dobra praktyka to walidacja dokumentu względem schematu XSD FA(3) zanim trafi do KSeF — pozwala to wyłapać błędy strukturalne od razu, zamiast dowiadywać się o nich dopiero po odrzuceniu przez system Ministerstwa Finansów.

Krok 3 — wysyłka dokumentu

Gotowy XML trafia do odpowiedniego endpointu API. Przy integracji przez API KSeFService wygląda to jako żądanie z plikiem XML w formacie multipart/form-data:

POST /api/v1/invoices/send
Content-Type: multipart/form-data

clientId, login, password, api_env, file (XML FA(3))

Krok 4 — odczyt statusu przetworzenia

Wysłanie żądania nie oznacza jeszcze, że faktura została zaakceptowana — to potwierdza dopiero status przetworzenia zwrócony przez system. Poprawna odpowiedź zawiera m.in. numer KSeF nadany dokumentowi:

{
  "success": true,
  "stage": "ksef_ok",
  "data": {
    "ksefNumber": "5771876968-20251209-0100805B192F-B3",
    "sessionReference": "20251209-SO-178C9DF000-9498D48B5B-BB"
  }
}

Krok 5 — pobranie UPO

Numer KSeF to jedno, ale formalnym dowodem doręczenia faktury do systemu jest Urzędowe Poświadczenie Odbioru (UPO) — pobierane osobnym żądaniem, na podstawie numeru referencyjnego sesji wysyłki. UPO warto zarchiwizować razem z oryginalnym dokumentem faktury.

Dlaczego faktura może zostać odrzucona

• Błąd walidacji XSD — niezgodność struktury dokumentu ze schematem FA(3).
• Błąd autoryzacji — niepoprawny certyfikat, token lub kontekst wysyłki.
• Błędne dane kontrahenta — np. niepoprawny NIP lub niekompletne dane adresowe.
• Niepoprawne stawki VAT lub sumy — rozbieżność między wartościami pozycji a sumami dokumentu.
• Błąd przejściowy po stronie KSeF — chwilowa niedostępność systemu, którą dobra integracja obsługuje przez ponowienie żądania, a nie przez natychmiastowe zgłoszenie błędu użytkownikowi.

Wysyłka pojedyncza a wysyłka wsadowa

Przy pojedynczych fakturach wysyłka interaktywna (jedna faktura, jedno żądanie) jest wystarczająca. Przy większym wolumenie — dziesiątkach czy setkach dokumentów — warto skorzystać z wysyłki wsadowej, uwzględniającej limity zapytań nakładane przez KSeF, żeby uniknąć odrzuceń wynikających z przekroczenia limitu w krótkim czasie. Więcej o tym pisaliśmy w artykule o wysyłce masowej faktur oraz o automatyzacji wysyłki przez gotowe skrypty.

Podsumowanie

Wysłanie faktury do KSeF przez API to proces złożony z kilku etapów, z których każdy może być źródłem błędu: przygotowanie poprawnego dokumentu FA(3), walidacja, wysyłka, odczyt statusu i pobranie UPO. Zrozumienie tego, na którym etapie faktycznie znajduje się problem, jest kluczowe przy debugowaniu integracji — „faktura się nie wysłała" rzadko oznacza to samo co „faktura została odrzucona przez KSeF".

Chcesz przetestować pełny, gotowy przykład wysyłki? Sprawdź praktyczny przykład integracji krok po kroku lub dokumentację API z przykładami kodu.