iFirma dla Shopify

Aplikacja łączy sklep Shopify z systemem iFirma, dzięki czemu wystawisz faktury VAT, faktury proforma i rachunki prosto z zamówień.

1. Instalacja i konfiguracja

iFirma by WP Desk integruje sklep Shopify z API iFirma. Aplikacja automatycznie tworzy i wysyła dokumenty sprzedaży, zapisuje ich historię przy zamówieniu oraz udostępnia ręczne akcje wystawiania dokumentów. Proces wydawania dokumentów jest zabezpieczony kolejką, która pilnuje, aby każde zamówienie było obsłużone dokładnie raz dla wybranego typu dokumentu.

Zanim rozpoczniesz konfigurację, upewnij się, że:

• masz aktywne konto Shopify (uprawnienia właściciela lub administratora aplikacji),
• posiadasz konto w iFirma z dostępem do API (plany Standard i wyższe),
• w iFirma możesz wygenerować trzy klucze API: Klucz abonenta, Klucz faktura i Klucz rachunek,
• w sklepie Shopify zebrałeś wymagane dane do wystawiania dokumentów (nazwa firmy, adres, NIP) – w razie potrzeby dodaj pola w checkout.

2. Instalacja aplikacji

1. Dodanie aplikacji – w panelu Shopify przejdź do Apps > Shopify App Store, wyszukaj iFirma by WP Desk i kliknij Add app.
2. Uprawnienia – po przekierowaniu do sklepu przejrzyj listę uprawnień (odczyt zamówień, zapisywanie danych aplikacji, Webhooki). Zatwierdź, wybierając Install app.
3. Pierwsze uruchomienie – aplikacja pojawi się na liście w zakładce Aplikacje. Otwórz ją i przejdź przez ekran powitalny do zakładki Ustawienia.
4. Dostosowanie widoku zamówienia – Shopify poprosi o potwierdzenie dodania bloków aplikacji w szczególe zamówienia. Kliknij Customize, dodaj blok iFirma – dokumenty oraz przypnij akcje Wystaw fakturę, Wystaw proformę i Wystaw rachunek. Dzięki temu obsługa zamówień będzie dostępna bez otwierania aplikacji w osobnej karcie.

Po tych krokach aplikacja poprosi o dane dostępowe do iFirma.

3. Autoryzacja z kontem iFirma

Sekcja Autoryzacja w ustawieniach aplikacji zbiera dane niezbędne do komunikacji z API iFirma. Formularz zawiera pola Login, Klucz abonenta, Klucz faktura oraz Klucz rachunek. Po zapisaniu wartości tokeny są szyfrowane, a w panelu widać jedynie maskę (ciąg gwiazdek), co zabezpiecza je przed podglądem.

3.1 Jak wygenerować klucze API

1. Zaloguj się do iFirma i przejdź do Narzędzia > API (lub Ustawienia > Integracje, zależnie od układu panelu).
2. W sekcji Klucze API kliknij Dodaj klucz i wybierz typ:
   • Klucz abonenta – używany do operacji na koncie (m.in. sprawdzenie/podmiana miesiąca księgowego).
   • Klucz faktura – wspólny token dla faktur VAT i faktur proforma.
   • Klucz rachunek – wymagany do wystawiania rachunków.
3. Skopiuj każdy wygenerowany token i wklej go w odpowiednie pole aplikacji Shopify. Tokeny są długimi ciągami znaków heksadecymalnych – upewnij się, że nie dodajesz spacji.

3.2 Status połączenia

Pod formularzem autoryzacji znajduje się baner Status połączenia z iFirmą. Po kliknięciu Zapisz (lub przy ręcznym użyciu przycisku Ponów) aplikacja łączy się z API iFirma i weryfikuje token Klucz abonenta. Komunikat sukcesu informuje dodatkowo, jaki miesiąc księgowy jest ustawiony na koncie iFirma. Jeśli tokeny są niepoprawne, baner zmieni kolor na czerwony i zasugeruje ponowne wprowadzenie kluczy.

Każde ręczne lub automatyczne wystawienie dokumentu wymusza także sprawdzenie miesiąca księgowego.

3.3 Integracja z KSeF

Wtyczka nie posiada własnych ustawień związanych z Krajowym Systemem e-Faktur (KSeF). Obsługa KSeF odbywa się w całości po stronie serwisu księgowego iFirma. Oznacza to, że po stronie wtyczki nie jest wymagane wykonywanie żadnych dodatkowych czynności ani konfiguracji dotyczących KSeF.

Jak włączyć KSeF w serwisie księgowym iFirma

Aby korzystać z KSeF, należy aktywować integrację bezpośrednio w panelu iFirma:

• Zaloguj się do swojego konta w iFirma.
• Przejdź do: Konfiguracja → Rozszerzenia i integracje → KSeF.
• Rozpocznij konfigurację integracji z KSeF zgodnie z instrukcjami wyświetlanymi w systemie.

Na tym etapie następuje konfiguracja po stronie systemu księgowego.

Co dzieje się po włączeniu integracji?

Po poprawnym włączeniu i skonfigurowaniu KSeF w panelu iFirma:

• faktury przesyłane z WooCommerce do iFirma będą automatycznie przekazywane do KSeF,
• cały proces wysyłki do KSeF realizowany jest przez iFirma,
• wtyczka iFirma WooCommerce nie wymaga żadnych dodatkowych ustawień w tym zakresie.

4. Ustawienia aplikacji

Ustawienia dokumentów zostały podzielone na trzy sekcje: Faktury, Faktury proforma, Rachunki.

Wszystkie sekcje korzystają ze wspólnej logiki:

• ustawienia automatycznego wystawiania reagują na webhooki Shopify Utworzony (orders/create), Opłacony (orders/paid) i Zrealizowany (orders/fulfilled),
• notatki oraz termin płatności są zapisywane również w historii dokumentu — widać je w panelu zamówienia oraz w logach iFirma,
• jeżeli automatyczna wysyłka e-mail jest aktywna, aplikacja wykorzystuje endpoint Wyślij dokument e-mailem, wysyłając PDF na adres klienta ze Shopify z serwisu iFirmy.

4.1 Ustawienia faktur

Konfiguracja faktur VAT obejmuje trzy obszary:

• Automatyczne tworzenie dokumentów – włącz, aby kolejka po otrzymaniu odpowiedniego webhooka utworzyła fakturę. Jeżeli opcja jest wyłączona, faktury wystawiasz ręcznie z poziomu zamówienia.
• Status zamówienia, który uruchamia wystawianie – do wyboru są statusy Utworzony, Opłacony i Zrealizowany. Każdy status jest powiązany z konkretnym webhookiem Shopify, co zapewnia powtarzalność i brak duplikatów.
• Automatyczna wysyłka dokumentów – po zaznaczeniu aplikacja po utworzeniu faktury wywoła w iFirma metodę wysyłki i prześle PDF na adres klienta z zamówienia.

Dodatkowo możesz ustawić:

• Uwagi na fakturze – dowolny tekst (np. numer magazynu, opis promocji). Pole jest przekazywane w każdym ręcznym i automatycznym wystawieniu.
• Termin płatności – 7, 14 lub 30 dni dodawane do daty wystawienia. Utrzymywane jest spójnie z ustawieniem wykorzystywanym przez ręczną akcję.

Wystawione faktury są zapisywane w bazie aplikacji wraz z numerem dokumentu, identyfikatorem iFirma oraz linkiem do PDF. Dzięki temu historia jest widoczna w szczegółach zamówienia.

4.2 Ustawienia faktur proforma

Faktury proforma działają identycznie jak faktury VAT, ale zwykle są generowane na wcześniejszym etapie procesu (np. zaraz po złożeniu zamówienia). Zalecane ustawienia:

• Automatyczne wystawianie – włącz i wybierz status Utworzony, aby wysyłać proformy natychmiast do klientów oczekujących na przelew.
• Termin płatności – ustaw zgodnie z polityką firmy (np. 7 dni). Wartość jest przekazywana w API i widać ją w PDF.
• Uwagi – użyj pola, aby dodać instrukcję płatności lub numer rachunku bankowego (jeżeli nie jest ustawiony w iFirma globalnie).
• Automatyczna wysyłka – jeśli chcesz wysłać proformę bezpośrednio z iFirma, zaznacz checkbox. W przeciwnym razie PDF będzie dostępny do pobrania z poziomu zamówienia.

Dodatkowo możesz ustawić:

• Uwagi na proformie – dowolny tekst (np. numer magazynu, opis promocji). Pole jest przekazywane w każdym ręcznym i automatycznym wystawieniu.
• Termin płatności – 7, 14 lub 30 dni dodawane do daty wystawienia. Utrzymywane jest spójnie z ustawieniem wykorzystywanym przez ręczną akcję.

Wystawione proformy są zapisywane w bazie aplikacji wraz z numerem dokumentu, identyfikatorem iFirma oraz linkiem do PDF. Dzięki temu historia jest widoczna w szczegółach zamówienia.

Pamiętaj, że finalna faktura VAT może być wystawiona automatycznie później (np. po opłaceniu), nawet jeśli proforma została wysłana wcześniej.

4.3 Ustawienia rachunków

Rachunki są obsługiwane oddzielnym tokenem API (Klucz rachunek). Konfiguracja jest spójna z pozostałymi dokumentami:

• określ, czy rachunek ma być generowany automatycznie i przy jakim statusie zamówienia;
• ustaw termin płatności i domyślne uwagi (np. nazwa kanału sprzedaży);
• włącz automatyczną wysyłkę, jeśli chcesz wysyłać rachunki klientom podobnie jak faktury.

Aplikacja zapisuje w bazie informację o tym, czy rachunek został wystawiony i wysłany, dzięki czemu obsługa klienta zawsze widzi w Shopify aktualny stan dokumentów.

4.4 Ustawienia ogólne

Sekcja Ustawienia ogólne decyduje, skąd aplikacja pobierze numer NIP klienta:

• Druga linia adresu (Address line 2) – wybierz, jeśli w checkout Shopify masz pole Adres, linia 2 i prosisz w nim o NIP.
• Uwagi do zamówienia – użyj, gdy klienci podają NIP w polu z notatką do zamówienia.

Warto przygotować instrukcję przy polu checkout (np. „Wpisz NIP”); aplikacja przepisze zawartość dokładnie tak, jak klient ją wprowadził. Jeżeli potrzebujesz dedykowanego pola NIP, możesz je dodać w Shopify Plus lub skorzystać z aplikacji rozszerzającej checkout – ustaw następnie odpowiednie źródło.

4.5 Ręczne wystawianie i podgląd dokumentów

Po dodaniu bloków aplikacji w szczególe zamówienia Shopify zyskujesz dwie funkcje:

1. Lista dokumentów – blok iFirma – dokumenty pokazuje wszystkie dokumenty zapisane dla danego zamówienia (typ, numer, data wystawienia). Każdy wpis zawiera link Podgląd PDF, który otwiera podpisany adres URL (generowany przez aplikację i zabezpieczony podpisem UriSigner). Link można przekazać księgowości; pozostaje aktywny do czasu zmiany podpisu.
2. Akcje „Wystaw dokument” – w panelu bocznym zamówienia pojawiają się trzy akcje: faktura, proforma i rachunek. Po kliknięciu otwiera się formularz z domyślnymi wartościami z ustawień (uwagi, termin płatności). Możesz:
   • zdecydować, czy dokument ma zostać wysłany bezpośrednio do klienta i na jaki adres e-mail,
   • zmienić treść notatki lub termin płatności tylko dla bieżącego dokumentu,
   • widzieć ostrzeżenie, gdy dokument danego typu już istnieje (przycisk zmienia się w destrukcyjny, ale nadal możesz wystawić duplikat – np. gdy koregujesz dane).

Po wysłaniu formularza aplikacja natychmiast rozpoczyna proces w tle: pobiera szczegóły zamówienia, ustawia poprawny miesiąc księgowy w iFirma, tworzy dokument, a na końcu (opcjonalnie) wysyła go e-mailem. Wynik operacji pojawia się jako baner w formularzu i w historii dokumentów.

5. Zakończenie

Po skonfigurowaniu tokenów, automatycznego wystawiania i źródła NIP integracja jest gotowa do pracy. Zachęcamy, aby przetestować proces na zamówieniu roboczym (np. utworzonym w walucie testowej), sprawdzić podgląd PDF oraz upewnić się, że e-maile z iFirma docierają do klientów.

W razie pytań skorzystaj z formularza wsparcia WP Desk.