Sklep internetowy lub własny system zamówień może przekazywać dane faktury do ksefv.pl przez API. Dzięki temu operator nie musi ponownie wpisywać tych samych pozycji. Integracja wymaga jednak więcej niż pojedynczego żądania: trzeba zaplanować dostęp, mapowanie danych i zachowanie po błędzie sieci.
Osobny klucz zamiast hasła użytkownika
Klucz tworzy właściciel firmy w „Ustawienia › Klucze API”. Pełna wartość jest pokazywana tylko raz i powinna trafić do bezpiecznej konfiguracji serwera sklepu, nigdy do kodu JavaScript uruchamianego u klienta. Dostępność API zależy od planu lub dodatku. Klucz działa w firmie, w której został utworzony — nie jest uniwersalnym dostępem do klientów biura.
Szkic, wystawienie i wysyłka to różne kroki
Żądanie POST /api/invoices może utworzyć szkic. Wystawienie wymaga dodatkowych uprawnień i prawidłowych danych, a wysyłka do KSeF jest osobną operacją. Sam zapis faktury nie potwierdza jej przyjęcia przez KSeF. Integrator powinien obsługiwać statusy i sprawdzać rezultat, zamiast uznawać wszystkie etapy za zakończone po pierwszej odpowiedzi.
Nie wysyłaj właściciela dokumentu
Firma i właściciel są ustalani po stronie serwera. Nie przekazuj pól user, userId ani tenantId w treści faktury. Uprawnienia klucza powinny ograniczać się do potrzebnych operacji: odczyt, zapis, wystawienie, pobranie PDF czy wysyłka do KSeF to odrębne zakresy.
Jak uniknąć podwójnej faktury?
Zapisuj powiązanie numeru zamówienia z identyfikatorem faktury. Po utracie odpowiedzi sprawdź rezultat przed ponownym utworzeniem dokumentu; nie zakładaj obsługi Idempotency-Key bez potwierdzenia w kontrakcie API. Przetestuj brak uprawnień, błędne dane, wygaśnięcie planu i odwołany klucz. Przed wdrożeniem uzgodnij aktualny kontrakt integracji przez kontakt z zespołem.
Uporządkuj pracę z dokumentami
Poznaj panel i wybierz funkcje odpowiednie dla Twojej firmy. Konfigurację integracji i sposób rozliczenia uzgodnij z księgowym.