Spis treści
- 1 1. Wprowadzenie
- 2 2. Instalacja i pierwsze uruchomienie
- 3 3. Jak otworzyć panel aplikacji
- 4 4. Opis sekcji interfejsu
- 5 5. Najważniejsze endpointy i komunikacja (dla użytkownika — informacyjnie)
- 6 6. Przykład użycia — konfiguracja automatycznego wystawiania faktury
- 7 7. FAQ — Najczęściej zadawane pytania
- 7.1 Q: Gdzie znajdę dane API (API Key / Secret) dla Fakturowni?
- 7.2 Q: Jak przetestować, czy aplikacja poprawnie komunikuje się z Fakturownią?
- 7.3 Q: Co oznacza komunikat „dokument już istnieje” / konflikt?
- 7.4 Q: Czy aplikacja automatycznie usuwa lub edytuje dokumenty w Fakturowni?
- 7.5 Q: Klient nie otrzymał e-maila z dokumentem — co sprawdzić?
- 7.6 Q: Gdzie klient może pobrać swoją fakturę?
- 8 8. Rozwiązywanie problemów — checklisty
- 9 9. Placeholdery obrazków (wstaw później)
- 10 10. Kontakt i dodatkowe informacje
1. Wprowadzenie
Integracja Fakturownia — Shopify umożliwia wystawianie dokumentów księgowych (faktur VAT, proform, paragonów) bezpośrednio z poziomu panelu Shopify oraz udostępnianie klientom linków do pobrania dokumentów. Aplikacja zawiera:
- Panel konfiguracji połączenia z Fakturownią (dane API / credentials).
- Formularz ręcznego wystawiania dokumentu z poziomu strony zamówienia (Issue Invoice / Receipt / Proforma).
- Blok w widoku szczegółów zamówienia pokazujący już wystawione dokumenty oraz link do podglądu PDF.
- Rozszerzenie konta klienta (Customer Account) umożliwiające pobranie dokumentów z poziomu statusu zamówienia.
- Mechanizm health-check sprawdzający łączność z usługą Fakturownia.
2. Instalacja i pierwsze uruchomienie
- Zainstaluj aplikację w panelu Shopify (Shopify App Store lub instalacja prywatna).
- Po instalacji przejdź do ustawień aplikacji — zwykle pod Aplikacje > Fakturownia w panelu administracyjnym.
- Przy pierwszym uruchomieniu aplikacja może poprosić o autoryzację i przyznanie wymaganych uprawnień (odczyt zamówień, dostęp admina itp.).
3. Jak otworzyć panel aplikacji
- W panelu administracyjnym Shopify kliknij Aplikacje.
- Wybierz Fakturownia z listy zainstalowanych aplikacji.
- Aplikacja otworzy się osadzona w panelu Shopify (embedded). Jeśli uruchomisz ją z zewnątrz, zobaczysz informację o tym, że należy otworzyć ją wewnątrz panelu.
4. Opis sekcji interfejsu
4.1. Autoryzacja — dane dostępu do Fakturowni
W sekcji autoryzacji wpisujesz dane, które aplikacja wykorzysta do komunikacji z API Fakturowni. Typowe pola widoczne w UI:
- API Key / Client ID — identyfikator konta / aplikacji
- API Secret / Token — sekret używany do autoryzacji
- ID firmy / numer konta — jeżeli wymagane przez Fakturownię
- Przycisk testuj połączenie lub komponent health-check — informuje, czy połączenie przebiega prawidłowo.
Po wpisaniu danych kliknij Zapisz. Aplikacja wykona health-check i pokaże banner z informacją o powodzeniu lub błędzie.
4.2. Sprawdzenie połączenia (Connectivity / Health check)
Komponent ConnectivityCheck (wyświetlany, jeśli włączony) pokazuje aktualny status łączności z backendem Fakturowni. Możliwe stany:
- Ładowanie — sprawdzanie połączenia.
- Sukces — połączenie OK.
- Ostrzeżenie / Błąd — brak dostępu lub problem z autoryzacją.
4.3. Ustawienia dokumentów
Aplikacja pozwala na wystawianie trzech typów dokumentów: Faktur, Faktur proforma, oraz Paragonów..
Ustawienia faktur
Ustawienia faktur:
- Metoda wystawiania – wybierz, czy wystawiać dokument ręcznie, czy dla wskazanego statusu zamówienia,
- Termin płatności – wybierz termin płatności, jaki ma być wyświetlony na dokumencie,
- Dział – wybierz dział/magazyn Fakturowni, w którym dodany jest produkt,
- Seria numeracji – ustaw numerację dla typu dokumentu,
- Numer bankowy – ustaw numer rachunku, który będzie widoczny na dokumentach,
- Numer bankowy – ustaw numer rachunku, który będzie widoczny na dokumentach,
- Dołącz numer zamówienia do notatek – zaznacz, aby numer zamówienia zawsze trafił do notatki na dokumencie,
- Dołącz metodę płatności do notatek – zaznacz, aby metoda płatności trafiała do notatki na dokumencie,
- Dodatkowa notatka do dokumentu – wpisz notatkę, która będzie widoczna na dokumencie,
- Kategoria – ustaw kategorię,
Ustawienia proform
Ustawienia proform:
- Metoda wystawiania – wybierz, czy wystawiać dokument ręcznie, czy dla wskazanego statusu zamówienia,
- Termin płatności – wybierz termin płatności, jaki ma być wyświetlony na dokumencie,
- Dział – wybierz dział/magazyn Fakturowni, w którym dodany jest produkt,
- Seria numeracji – ustaw numerację dla typu dokumentu,
- Numer bankowy – ustaw numer rachunku, który będzie widoczny na dokumentach,
- Numer bankowy – ustaw numer rachunku, który będzie widoczny na dokumentach,
- Kategoria – ustaw kategorię,
Ustawienia paragonów
Ustawienia paragonów:
- Metoda wystawiania – wybierz, czy wystawiać dokument ręcznie, czy dla wskazanego statusu zamówienia,
- Typ paragonów – wybierz, czy wystawiać paragon fiskalny, czy niefiskalny,
- Termin płatności – wybierz termin płatności, jaki ma być wyświetlony na dokumencie,
- Dział – wybierz dział/magazyn Fakturowni, w którym dodany jest produkt,
- Seria numeracji – ustaw numerację dla typu dokumentu,
- Numer bankowy – ustaw numer rachunku, który będzie widoczny na dokumentach,
- Numer bankowy – ustaw numer rachunku, który będzie widoczny na dokumentach,
- Dołącz numer zamówienia do notatek – zaznacz, aby numer zamówienia zawsze trafił do notatki na dokumencie,
- Dołącz metodę płatności do notatek – zaznacz, aby metoda płatności trafiała do notatki na dokumencie,
- Dodatkowa notatka do dokumentu – wpisz notatkę, która będzie widoczna na dokumencie,
- Kategoria – ustaw kategorię,
>4.4.Pozycje dokumentów
- Uwzględnij pozycje o wartościach zerowych – zaznacz, jeśli chcesz, aby na fakturę trafiały pozycje o wartościach zerowych,
- Uwzględnij wysyłkę o wartościach zerowych na dokumentach sprzedaży – zaznacz, jeśli chcesz, aby na fakturę trafiały pozycje wysyłki, które mają wartość równą zeru,
- Pole źródłowe identyfikatora podatkowego – wybierz pole, które używasz jako pola NIP w formularzu zamówienia.
4.5. Ręczne wystawianie dokumentu (ręczne wystawianie)
Z poziomu strony zamówienia (Admin Order Actions) dostępna jest akcja Wystaw Fakturę / Paragon / Proforma, która umożliwia wystawienie dokumentu do wybranego zamówienia.
5. Najważniejsze endpointy i komunikacja (dla użytkownika — informacyjnie)
Poniżej podane są endpointy, których używa interfejs aplikacji. Przydatne przy debugowaniu lub kontaktach z pomocą techniczną.
| Ścieżka | Cel |
|---|---|
GET /api/fakturownia/health-check |
Sprawdzenie łączności z backendem / Fakturownią (health check). |
POST /api/invoices |
Wystawienie dokumentu (wywoływane z formularza Issue Invoice/Receipt/Proforma). |
GET /api/order/{orderId}/invoices |
Pobranie listy dokumentów powiązanych z danym zamówieniem (wyświetlane w bloku na stronie zamówienia oraz w rozszerzeniu klienta). |
GET /api/merchant/settings |
Pobranie zapisanych ustawień aplikacji (wyświetlane jako surowe dane w panelu ustawień). |
POST /api/merchant/settings |
Zapisanie ustawień aplikacji. |
6. Przykład użycia — konfiguracja automatycznego wystawiania faktury
Przykładowy scenariusz: chcesz, aby faktury VAT były automatycznie wystawiane w Fakturowni, gdy zamówienie zostanie opłacone.
Krok 1 — Uzyskaj dane dostępu do Fakturowni
- Zaloguj się do panelu Fakturowni i wygeneruj dane API (API Key / Token / Client ID i Secret) zgodnie z instrukcjami Fakturowni.
- Zanotuj ID firmy / numer konta, jeśli jest wymagane.
Krok 2 — Wprowadź dane w panelu aplikacji
- Przejdź do Ustawienia → Autoryzacja w aplikacji Fakturownia w Shopify.
- Wklej odpowiednie pola: API Key, API Secret, (opcjonalnie) Company ID.
- Kliknij Zapisz. Komponent health-check powinien potwierdzić poprawne połączenie.
Krok 3 — Włącz automatyczne wystawianie dla faktur VAT
- W sekcji Ustawienia → Faktury VAT zaznacz, jeśli istnieje, opcję włączenia automatycznego wystawiania (jeśli aplikacja implementuje auto-issuing).
- Jeżeli dostępne, wybierz status zamówienia, który ma wyzwalać wystawienie (np.
paid— po opłaceniu). - Skonfiguruj domyślny termin płatności (np. 14 dni) oraz opcję automatycznego wysyłania e-maila do klienta po wystawieniu.
Krok 4 — Zapisz i przetestuj
- Zapisz ustawienia w aplikacji.
- Złóż testowe zamówienie lub zaktualizuj status istniejącego zamówienia na
paid. - Sprawdź blok „Wystawione Faktury” na stronie zamówienia oraz listę dokumentów w panelu Fakturowni.
7. FAQ — Najczęściej zadawane pytania
Q: Gdzie znajdę dane API (API Key / Secret) dla Fakturowni?
A: Na swoim koncie Fakturownia, w sekcji ustawień integracji / API. Instrukcje generowania tokenów / kluczy znajdziesz w dokumentacji Fakturowni lub kontaktując się z ich pomocą techniczną.
Q: Jak przetestować, czy aplikacja poprawnie komunikuje się z Fakturownią?
A: W panelu ustawień po zapisaniu danych autoryzacyjnych powinien pojawić się banner health-check potwierdzający sukces. Dodatkowo możesz spróbować ręcznie wystawić dokument z poziomu zamówienia i sprawdzić wynik.
Q: Co oznacza komunikat „dokument już istnieje” / konflikt?
A: Backend Fakturowni może zgłosić, że dokument o takich danych (np. numerze zamówienia) już istnieje. Formularz wystawiania w UI obsługuje taką sytuację i daje możliwość wymuszenia wystawienia (przycisk Wystaw mimo to), jeśli chcesz spróbować ponownie.
Q: Czy aplikacja automatycznie usuwa lub edytuje dokumenty w Fakturowni?
A: Nie — aplikacja wystawia dokumenty. Usuwanie lub edycja trzeba wykonać bezpośrednio w panelu Fakturowni.
Q: Klient nie otrzymał e-maila z dokumentem — co sprawdzić?
A: Sprawdź, czy w formularzu wystawiania zaznaczono opcję Wyślij dokument emailem, czy adres email klienta jest poprawny oraz czy Fakturownia nie zwróciła błędu podczas wysyłki. Logi i komunikaty zwrotne w aplikacji mogą pomóc zdiagnozować problem.
Q: Gdzie klient może pobrać swoją fakturę?
A: Jeśli aplikacja jest skonfigurowana z rozszerzeniem konta klienta, linki do pobrania dokumentów pojawią się w sekcji statusu zamówienia na koncie klienta. Ponadto pliki PDF są dostępne w panelu Fakturowni.
8. Rozwiązywanie problemów — checklisty
Brak połączenia (Health check error)
- Sprawdź, czy wprowadzone dane API są poprawne (klucz, sekret, ID firmy).
- Sprawdź, czy token ma ważne uprawnienia po stronie Fakturowni.
- Sprawdź, czy Twój serwer (aplikacja) ma dostęp do internetu / czy nie blokują go firewall / CORS.
Formularz zwraca błąd przy wystawianiu dokumentu
- Sprawdź treść komunikatu błędu — może to brakujące pole (np. email) lub nieprawidłowy format danych.
- Jeśli komunikat mówi o konflikcie (duplicate) — użyj opcji Wystaw mimo to, jeżeli to bezpieczne.
- Sprawdź logi backendu (jeśli masz dostęp) lub zgłoś błąd do zespołu wsparcia z treścią błędu.
9. Placeholdery obrazków (wstaw później)
Wstaw poniższe pliki w katalogu images/ i zamień placeholdery w dokumencie:
images/fakturownia-welcome.png— ekran powitalny aplikacjiimages/fakturownia-auth.png— sekcja Autoryzacja (API Key / Secret)images/fakturownia-health-check.png— banner health-checkimages/fakturownia-issue-form.png— formularz wystawiania faktury / paragonuimages/fakturownia-admin-block.png— blok „Wystawione Faktury” w panelu zamówieniaimages/fakturownia-customer-download.png— linki do pobrania dla klienta
images/fakturownia-welcome.png
10. Kontakt i dodatkowe informacje
Jeżeli potrzebujesz dodatkowej pomocy:
- Skontaktuj się z pomocą techniczną Fakturowni — w sprawach związanych z tokenami i API.
- Skontaktuj się z naszym zespołem wsparcia aplikacji.
- Przy zgłaszaniu błędu podaj: ID sklepu, numer zamówienia, zrzut ekranu i (jeśli występuje) treść błędu zwróconego przez API.