# KSeF

Integracja KSeF z Ritevo: podłączenie certyfikatem KSeF, wysyłanie faktur i korekt w trybie online, numer KSeF, ponowne połączenie.

Integracja z KSeF wysyła faktury i korekty wystawione w Ritevo do Krajowego Systemu e-Faktur. Podłączasz ją certyfikatem KSeF, a faktury trafiają do KSeF w trybie online.

> **Wymagana integracja:** Potrzebujesz NIP-u firmy i certyfikatu KSeF do uwierzytelniania: pliku klucza prywatnego (.key), hasła do tego klucza i pliku certyfikatu (.pem albo .crt).

Integracji KSeF możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innymi danymi albo innymi ustawieniami wystawiania dokumentów. Każda działa osobno.

Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami.

`externalId` to NIP. Nowy certyfikat podasz przez `PUT /integrations/accountings/ksef/{id}/certificate` - w każdym stanie integracji. Po udanym logowaniu do KSeF ustawia `authError=false` i `active=true`.

## Jakie dokumenty przesyła

- **Faktura VAT** (API: "Faktura VAT" = `INVOICE`; wartość w `billingType`) - trafia do KSeF jako faktura podstawowa.
- **Korekta faktury** (API: "Korekta faktury" = `CORRECTION`; wartość w `billingType`) - trafia do KSeF jako faktura korygująca.
- **Paragon** (API: "Paragon" = `RECEIPT`; wartość w `billingType`) - nie jest obsługiwany.

## Jak zdobyć certyfikat KSeF

Certyfikat generujesz w Aplikacji Podatnika KSeF Ministerstwa Finansów. Hasła do klucza prywatnego nie da się odzyskać, więc zapisz je razem z oboma plikami - podasz je w Ritevo przy dodawaniu integracji. Jeśli zgubisz hasło albo plik klucza, jedyne wyjście to wygenerować nowy certyfikat z nową parą kluczy.

1. Zaloguj się do Aplikacji Podatnika KSeF, na przykład profilem zaufanym.
2. W sekcji certyfikatów wybierz **Wnioskuj o certyfikat**.
3. Wybierz certyfikat do uwierzytelniania, wpisz jego nazwę i ustaw hasło do klucza prywatnego.
4. Kliknij **Generuj**. Plik klucza prywatnego (.key) zapisze się na Twoim komputerze.
5. Gdy wniosek zostanie zatwierdzony, pobierz plik certyfikatu (.crt).

## Podłączenie konta

Zacznij w Ritevo:

1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu.
2. W sekcji **Księgowość** wybierz kafelek **KSeF**.
3. W polu **Nazwa konta** wpisz własną nazwę integracji, a w polu **Nip** - NIP firmy, dla której wystawiasz faktury.
4. Dodaj **Plik klucza prywatnego (.key)**, wpisz **Hasło klucza** i dodaj **Plik certyfikatu (.pem/.crt)**.
5. Kliknij **Utwórz integrację**. Od razu logujemy się tym certyfikatem do KSeF: jeśli się uda, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd i nic nie zostanie zapisane.

![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp)

![Ekran Dodaj integrację z zaznaczonym kafelkiem KSeF w sekcji Księgowość](https://ritevo.com/docs/integrations/ksef/pl-catalogue.webp)

![Ekran dodawania integracji KSeF z polami Nazwa konta, Nip, plikami certyfikatu i hasłem klucza](https://ritevo.com/docs/integrations/ksef/pl-add.webp)

## Ustawienia integracji

Na stronie integracji znajdziesz:

- **Faktury są wysyłane w trybie online** - każda faktura trafia do KSeF od razu po przesłaniu.
- **Nazwa konta** - Twoja własna nazwa integracji. Zmieniasz ją i zapisujesz przyciskiem **Zaktualizuj integrację**.
- **Zaktualizuj dane logowania** - podajesz nowe pliki i hasło, na przykład gdy certyfikat wygasa. Sprawdzamy je w KSeF tak samo jak przy dodawaniu.

Tworzenie: `accountName`, `nip`, `certificateBase64` (plik .key w Base64), `certificatePassword` i `certificatePemBase64` (plik .pem albo .crt w Base64). Nazwę zmieniasz przez `PATCH /integrations/accountings/ksef/{id}` z `accountName`, a certyfikat przez `PUT /integrations/accountings/ksef/{id}/certificate` z tymi samymi trzema polami certyfikatu.

![Szczegóły integracji KSeF: informacja o trybie online, nazwa konta i przycisk Zaktualizuj dane logowania](https://ritevo.com/docs/integrations/ksef/pl-details.webp)

## Przesyłanie dokumentów

> **Warto wiedzieć:** Na jednym zamówieniu może być tylko jedna aktywna faktura i jeden aktywny paragon. Kolejny dokument tego typu wystawisz dopiero po usunięciu poprzedniego. Korekt do faktury możesz wystawić dowolnie wiele.

Dokumenty wystawiasz w zamówieniu. Do KSeF przesyłasz je na dwa sposoby:

- **Ręcznie** - w szczegółach dokumentu, w karcie **Zew. systemy księgowe**, kliknij przycisk z nazwą konta KSeF. Przycisk pojawia się tylko przy dokumentach, które ta integracja obsługuje.
- **Automatycznie** - krokiem **Prześlij fakturę do zew. systemu księgowego** albo **Prześlij paragon do zew. systemu księgowego** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions).

Przesyłanie dokumentów najlepiej zaplanować po kolei - najpierw wystawienie, potem przesłanie:

- **Faktura** - pierwsza akcja kończy się krokiem **Wygeneruj fakturę**. Druga startuje wyzwalaczem **Faktura(dodanie/usunięcie)**, ma warunek **Posiada fakturę** i krok **Prześlij fakturę do zew. systemu księgowego**.
- **Paragon** - tak samo: pierwsza akcja kończy się krokiem **Wygeneruj paragon**, a druga startuje wyzwalaczem **Paragon(dodanie/usunięcie)**, ma warunek **Posiada paragon** i krok **Prześlij paragon do zew. systemu księgowego**.
- **Korekty** - do jednej faktury możesz wystawić wiele korekt. Każdą prześlij zaraz po wystawieniu, zanim wystawisz następną.

> **Warto wiedzieć:** Krok przesłania wysyła zawsze tylko jeden dokument - najnowszy nieusunięty danego typu. Jeśli najpierw wystawisz wszystkie dokumenty, a dopiero potem włączysz przesyłanie, trafi tylko ostatni, a pozostałe prześlesz ręcznie. Usuniętego dokumentu nie prześlesz.

W tej samej karcie każde przesłanie ma swoją ikonę. Po najechaniu na nią widzisz konto, stan i datę:

- **W trakcie przesyłania** (API: "W trakcie przesyłania" = `PENDING`; wartość w `externalTransfers[].status`) - dokument jest wysłany, czekamy na potwierdzenie od KSeF.
- **Przesłano pomyślnie** (API: "Przesłano pomyślnie" = `SUCCESS`; wartość w `externalTransfers[].status`) - dokument jest w KSeF. Kliknij ikonę, żeby go pobrać albo otworzyć.
- **Błąd podczas przesyłania** (API: "Błąd podczas przesyłania" = `FAILED`; wartość w `externalTransfers[].status`) - dokument nie trafił do KSeF. Pod stanem widzisz powód błędu.

> **Warto wiedzieć:** Jeden dokument ma do danej integracji tylko jedno przesłanie: prześlesz go tam raz. Jeśli przesłanie skończy się błędem, możesz je ponowić tym samym przyciskiem. Do innej integracji księgowej ten sam dokument prześlesz osobno.

Akcje dla zamówień: kroki **Prześlij fakturę do zew. systemu księgowego** i **Prześlij paragon do zew. systemu księgowego** to `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` w `actionSteps[].action.type`, z `uuidValue` = id integracji księgowej (`GET /integrations/accountings`). Wyzwalacze **Przesłano fakturę w zew. systemie księgowym** i **Przesłano paragon w zew. systemie księgowym** to `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. Warunki **Ma udany transfer faktury do zew. systemu księgowego** / **Nie ma udanego transferu faktury do zew. systemu księgowego** = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, a dla paragonu `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = id integracji księgowych). Liczy się tylko przesłanie `SUCCESS`. Krok bierze ostatni dokument z `billings[]` zamówienia o danym `billingType` (`INVOICE` albo `RECEIPT`) z `deleted` = `false`. Na zamówieniu jest najwyżej jeden dokument danego `billingType` z `deleted` = `false` - próba wystawienia drugiego zwraca `BILLING_ALREADY_EXISTS`. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions).

### Jak faktura trafia do KSeF

- **Potwierdzenie** - KSeF przetwarza fakturę po otrzymaniu, więc najpierw ma ona stan **W trakcie przesyłania**. Sprawdzamy odpowiedź KSeF co kilka sekund. Jeśli KSeF nie potwierdzi faktury w ciągu 24 godzin, przesłanie kończy się błędem.
- **Numery i data** - na fakturze jest numer nadany w Ritevo. Po przyjęciu KSeF nadaje jej numer KSeF. Datą wystawienia w KSeF jest dzień przesłania.
- **PDF** - kliknięcie ikony pobiera PDF przygotowany z faktury zapisanej w KSeF, z numerem KSeF.
- **Korekty** - przesyłasz je ręcznie. Akcje automatyczne przesyłają tylko faktury i paragony.
- **Stawki VAT** - KSeF przyjmuje od nas 23%, 8%, 5%, 0%, WDT, Zw. i O.o, a także dawne 22% i 7%. Stawki OSS przesyłamy jako sprzedaż OSS. Faktura z inną stawką nie zostanie przesłana - zobaczysz błąd **Stawka podatku nie jest wspierana**.

## Wymaga ponownego połączenia

Ten stan pojawia się, gdy KSeF przestał akceptować certyfikat - na przykład po jego wygaśnięciu albo unieważnieniu. Do tego czasu faktury nie trafią do KSeF.

1. Wygeneruj nowy certyfikat KSeF - tak samo jak przy pierwszym podłączeniu.
2. Na stronie integracji kliknij **Zaktualizuj dane logowania**, dodaj nowe pliki, wpisz hasło i zatwierdź. Poprawny certyfikat odświeży połączenie, a historia przesłanych faktur zostaje bez zmian.

> **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać.

W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony.

![Okno Zaktualizuj dane logowania w integracji KSeF z polami na plik klucza prywatnego, hasło klucza i plik certyfikatu](https://ritevo.com/docs/integrations/ksef/pl-update.webp)

## Usunięcie integracji

**Usuń integrację** wyłącza integrację w Ritevo. Dokumenty przesłane wcześniej zostają w KSeF. **Przywróć integrację** włącza ją z powrotem.

## Czego integracja nie robi

- Nie przesyła paragonów.
- Nie wysyła faktur w trybie offline - tylko online.
- Nie zmienia faktur, które już trafiły do KSeF - zmianę wprowadzasz korektą.
- Nie pobiera z KSeF faktur zakupowych ani innych dokumentów.

## Integracja przez API

Endpointy tej integracji są pod `/integrations/accountings/ksef`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/accountings`. Dokument przesyłasz przez `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs.


---

Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.