KSeF a wysyłka e-mail z fakturą przez API – najczęstsze pytania
Zachowanie API przy wysyłce e-maila przed nadaniem numeru KSeF
Co się dzieje, gdy faktura nie trafiła jeszcze do KSeF, a przez API wywołana zostaje wysyłka e-maila?
Zachowanie systemu zależy od typu odbiorcy faktury:
-
Faktura na osobę prywatną (konsumenta) – e-mail zostaje wysłany od razu, niezależnie od statusu wysyłki do KSeF. Osoby prywatne nie są objęte obowiązkiem wysyłki faktur do KSeF, dlatego system nie wstrzymuje wysyłki. API zwraca status HTTP 200.
-
Faktura na firmę – wysyłka e-maila jest blokowana do momentu nadania fakturze numeru KSeF i kodów QR. API zwraca status HTTP 200, ale w odpowiedzi pojawia się komunikat:
“Faktura nie może zostać wysłana - brak numeru KSeF”
Po skutecznym przesłaniu faktury do KSeF e-mail zostaje wysłany automatycznie – bez konieczności ponownego wywoływania żądania przez API.
Kody QR na fakturze
Liczba kodów QR zależy od trybu wysyłki do KSeF, a nie od tego, czy faktura jest wystawiona na firmę, czy osobę prywatną:
| Tryb | Liczba kodów QR |
|---|---|
| Online | 1 kod QR |
| Offline / Offline24 | 2 kody QR |
Faktura wysłana e-mailem lub pobrana jako PDF przed nadaniem numeru KSeF nie zawiera żadnego kodu QR ani numeru KSeF – niezależnie od typu odbiorcy.
Czy faktura dla konsumenta bez kodu QR jest legalna?
Tak. KSeF nie wymaga wysyłania faktur dla osób prywatnych (konsumentów) do KSeF – obowiązek ten dotyczy wyłącznie faktur wystawianych na firmy. Osoby prywatne nie mają również możliwości logowania się do KSeF, aby przeglądać tam swoje faktury. Wysłanie faktury dla konsumenta bez kodu QR jest zatem w pełni zgodne z przepisami.
Jak sprawdzić przez API, czy e-mail z fakturą został wysłany?
Aktywności związane z wysyłką e-maili można pobrać za pomocą endpointu:
GET /activities.json?kind=send_invoice
- activitable_id – ID faktury, której dotyczy aktywność
- status – aktualny status wysyłki
Możliwe wartości statusu:
| Status | Opis |
|---|---|
| delivered | E-mail dostarczony |
| bounce | E-mail odrzucony przez serwer odbiorcy |
| dropped | E-mail porzucony (np. brak treści lub linku) |
| error | Błąd wysyłki |
| own_server | Wysyłka z własnego serwera SMTP (plan Pro i wyższe) |
Przykładowa odpowiedź API:
{
"id": 123,
"kind": "send_invoice",
"status": "error",
"details": {
"to": "adres@email.com",
"reason": "No invoice link nor attachment in email body"
},
"activitable_id": 123456789,
"activitable_type": "Invoice",
"created_at": "2022-10-07T15:23:02.000+02:00"
}
Ograniczenia endpointu /activities.json
- Nie ma możliwości pobrania aktywności wyłącznie dla jednej konkretnej faktury – endpoint zwraca aktywności dla całego konta.
- Endpoint activities.json nie posiada osobnej dokumentacji publicznej.
Ponawiane wysyłki e-maili
Fakturownia nie ponawia automatycznie wysyłek e-maili – niezależnie od rodzaju błędu. W przypadku nieudanej wysyłki należy ponowić ją ręcznie w panelu lub poprzez API.
Wyjątek: Jeśli wysyłka e-maila z fakturą na firmę została odroczona z powodu braku numeru KSeF, zostanie ona wykonana automatycznie po nadaniu numeru KSeF – bez konieczności ponownego wywołania żądania.
Tryb Offline24 a wysyłka faktur przez API
Tryb Offline24 jest obsługiwany dla faktur wystawianych przez API. Faktury wystawione w tym trybie są automatycznie ponawiane do wysyłki do KSeF do momentu jej skutecznego zakończenia.
Więcej informacji o trybach awaryjnych: Tryby awaryjne offline i offline24