Fakturownia MCP czy własna integracja Symfony?

Oficjalna integracja daje asystentowi AI trzy narzędzia tylko do odczytu: wyszukiwanie faktur, pobieranie szczegółów kontrahenta oraz obliczanie zagregowanych rozliczeń kontrahenta. Autoryzacja odbywa się przez OAuth 2.1 z PKCE, dostęp dotyczy konkretnego konta i można go później cofnąć.

To rozsądny zakres dla pytań takich jak:

• które faktury nadal czekają na płatność,

• ile dany kontrahent ma do zapłaty w określonej walucie,

• jakie dane kontaktowe zapisano przy kliencie,

• jak wygląda suma wystawionych i opłaconych dokumentów.

Połączenie jest wymuszane jako read-only na poziomie bazy danych Fakturowni. Asystent nie może za jego pomocą utworzyć ani zmienić dokumentu. Według aktualnej informacji producenta rozszerzenie oficjalnego MCP o wystawianie faktur nie jest obecnie planowane.

Aktualny zakres i instrukcję konfiguracji warto sprawdzać bezpośrednio w dokumentacji MCP Fakturowni, ponieważ ta funkcja może się rozwijać.

Jeśli pracę inicjuje człowiek, a asystent ma jedynie znaleźć i podsumować dane, oficjalne MCP będzie zwykle najlepszym pierwszym wyborem. Jest gotowe, nie wymaga developmentu i ogranicza zakres do odczytu.

Jeśli natomiast proces ma wykonać sama aplikacja — na przykład po opłaceniu zamówienia utworzyć klienta, wystawić fakturę, zapisać jej identyfikator i uruchomić kolejny etap — potrzebujesz warstwy opartej na API.

**

Oficjalne MCP odpowiada na pytanie: „co asystent może odczytać?”. Własna integracja odpowiada na pytanie: „jak nasz system ma bezpiecznie wykonać konkretny proces?”.

**

To rozróżnienie jest ważniejsze niż wybór samego protokołu. MCP nie zastępuje reguł biznesowych, transakcji, autoryzacji użytkownika aplikacji ani obsługi błędów w procesie.

Najuczciwiej porównać oba rozwiązania w kilku praktycznych wymiarach.

• Użytkownik. Oficjalne MCP służy osobie pracującej z asystentem AI. Bundle służy przede wszystkim aplikacji Symfony, a dopiero opcjonalnie wystawia wybrane przypadki użycia agentowi.

• Zakres. Oficjalne MCP udostępnia trzy operacje odczytowe. Własna warstwa może korzystać z szerszego API, ale jej zakres powinien wynikać z konkretnego procesu, nie z możliwości dostawcy.

• Zmiana danych. Oficjalne MCP nie zapisuje danych. Integracja API może tworzyć i aktualizować dokumenty, dlatego wymaga dodatkowych zabezpieczeń.

• Reguły biznesowe. Gotowy konektor nie zna domeny Twojej aplikacji. Własna warstwa może sprawdzić stan zamówienia, uprawnienia, limit, duplikat i warunki akceptacji przed wykonaniem operacji.

• Koszt wdrożenia. Oficjalne MCP można podłączyć bez developmentu. Bundle ma sens dopiero wtedy, gdy oszczędza ręczną pracę albo porządkuje proces, który i tak musi istnieć w systemie.

Nie warto budować własnej integracji tylko po to, żeby zadać kilka pytań o dane. Nie warto też wciskać procesu transakcyjnego w narzędzie zaprojektowane do analizy tylko do odczytu.

Gotowa integracja jest dobrym wyborem, gdy potrzebujesz szybkiego dostępu analitycznego i nie chcesz utrzymywać własnego kodu. Szczególnie wtedy, gdy:

• użytkownik sam rozpoczyna rozmowę i ocenia odpowiedź asystenta,

• wystarczy wyszukiwanie faktur, dane kontrahenta i agregaty rozliczeń,

• operacja nie może zmieniać danych w Fakturowni,

• nie musisz łączyć wyniku z własnym modelem zamówień, uprawnień lub akceptacji,

• najważniejszy jest krótki czas uruchomienia i brak kosztu developmentu.

Trzeba przy tym świadomie ocenić dane przekazywane do wybranego asystenta. Oficjalna dokumentacja wskazuje, że integracja ma jeden wspólny zakres dla trzech narzędzi i nie pozwala dziś wyłączyć wybranych pól danych kontrahenta. Nie oferuje też automatycznego maskowania danych osobowych. To nie musi przekreślać zastosowania, ale powinno być częścią decyzji właściciela danych, a nie przypadkowym efektem konfiguracji.

Własna integracja zaczyna mieć sens, gdy Fakturownia jest elementem procesu produktu, a nie tylko źródłem informacji dla człowieka.

Typowe przykłady to:

• wystawienie faktury po spełnieniu warunków zamówienia lub subskrypcji,

• utworzenie kontrahenta po walidacji danych z CRM albo portalu B2B,

• powiązanie dokumentu z wewnętrznym identyfikatorem i dalszym workflow,

• sprawdzenie płatności w zadaniu cyklicznym i zmiana statusu procesu,

• wymuszenie limitów, akceptacji i uprawnień przed operacją zapisu,

• udostępnienie agentowi tylko wąskiej operacji zdefiniowanej przez Twoją domenę.

Publiczne API Fakturowni obsługuje między innymi tworzenie, aktualizację i usuwanie faktur. Sam fakt istnienia endpointu nie oznacza jednak, że powinien on zostać bezpośrednio wystawiony agentowi. Najpierw potrzebna jest warstwa, która zamienia techniczną możliwość w kontrolowany przypadek użycia.

Bundle powstał po to, żeby integracja była normalną częścią aplikacji Symfony, a nie zbiorem wywołań HTTP rozrzuconych po kontrolerach i handlerach.

Publicznym wejściem jest typowany FakturowniaInterface. Pod nim znajdują się commands, queries, DTO, value objects i adapter gateway odpowiedzialny za komunikację z API. Warstwa MCP korzysta z tych samych przypadków użycia zamiast budować drugi, równoległy model integracji.

W aktualnej wersji pakiet udostępnia sześć narzędzi:

• list_invoices i get_invoice,

• create_invoice,

• list_clients i create_client,

• invoice_payment_status.

Ten zestaw nie próbuje odwzorować całego API. Obejmuje operacje, które da się zamknąć w czytelnym kontrakcie i przetestować. Kod pakietu, sposób instalacji oraz wymagania są dostępne w repozytorium codevenom/fakturownia-bundle.

Osobny serwis ma sens, gdy integracja potrzebuje własnego cyklu wdrożeń, niezależnego skalowania, wielu klientów technologicznych albo wyraźnie odrębnego właściciela. W przeciwnym razie może jedynie dodać sieć, deployment, obserwowalność i kolejne miejsce awarii.

Bundle jest rozsądniejszy, gdy:

• proces biznesowy już należy do aplikacji Symfony,

• te same DTO i reguły mają obsługiwać użytkownika, zadanie w tle oraz narzędzie MCP,

• operacje powinny uczestniczyć w istniejącym logowaniu, obsłudze błędów i monitoringu,

• nie ma potrzeby wystawiania integracji kilku niezależnym systemom.

To nie jest zasada „mikroserwisy są złe”. Chodzi o koszt granicy. Jeśli oddzielenie nie daje biznesowej niezależności, powstaje kolejny komponent, który trzeba utrzymywać bez proporcjonalnej korzyści.

Oficjalne MCP ogranicza ryzyko przez tryb tylko do odczytu. Własna integracja może wykonywać operacje zapisu, więc jej projekt musi być bardziej restrykcyjny. Narzędzie create_invoice nie powinno oznaczać „agent może wystawić dowolny dokument z dowolnymi danymi”.

Minimalny zestaw kontroli obejmuje:

• przechowywanie tokenu API wyłącznie po stronie serwera,

• jawny allowlist operacji i pól dostępnych w danym procesie,

• walidację danych oraz reguł biznesowych przed wywołaniem API,

• kontrolę uprawnień użytkownika lub procesu inicjującego operację,

• idempotencję i ochronę przed utworzeniem duplikatu,

• rejestr decyzji, parametrów i wyniku operacji,

• mechanizm akceptacji dla działań o większym wpływie,

• obsługę timeoutów, retry i niejednoznacznego wyniku zapisu.

Sam pakiet jest elementem architektury, nie certyfikatem bezpieczeństwa ani zgodności. Ostateczne zabezpieczenia muszą wynikać z procesu, danych i ryzyka konkretnej aplikacji.

Zanim rozpoczniesz development, przejdź przez cztery pytania:

• Czy wystarczy odczyt danych przez człowieka pracującego z asystentem? Jeśli tak, zacznij od oficjalnego MCP.

• Czy system ma tworzyć lub zmieniać dane jako część procesu? Jeśli tak, potrzebujesz integracji API z własnymi regułami.

• Czy proces należy do istniejącej aplikacji Symfony? Jeśli tak, bundle zwykle będzie prostszą granicą niż osobny serwis.

• Czy integrację musi współdzielić wiele aplikacji i zespołów? Dopiero wtedy warto poważnie rozważyć niezależny serwis.

Najtańsza poprawna decyzja często brzmi: użyj oficjalnego MCP i niczego nie buduj. Własna warstwa ma przewagę dopiero wtedy, gdy zamienia ręczny, powtarzalny proces w kontrolowaną część produktu.

Czy codevenom/fakturownia-bundle zastępuje oficjalne MCP?

Nie. Oficjalne MCP jest dobrym interfejsem do kontrolowanego odczytu przez asystenta. Bundle jest przeznaczony dla aplikacji Symfony, które potrzebują typowanej integracji API i własnych przypadków użycia.

Czy bundle może wystawiać faktury?

Tak. Aktualna wersja zawiera narzędzie create_invoice oraz przypadek użycia dostępny przez typowany kontrakt. Sposób uruchomienia tej operacji i wymagane akceptacje powinny wynikać z procesu konkretnej aplikacji.

Czy trzeba włączać MCP, żeby używać pakietu?

Nie. Pakiet może działać jak zwykła biblioteka Symfony przez FakturowniaInterface. Warstwa MCP jest dodatkowym wejściem do tych samych przypadków użycia.

Czy takie rozwiązanie nadaje się tylko do faktur?

Nie. Ten sam wzorzec sprawdza się w portalach B2B i systemach operacyjnych, gdy zewnętrzna usługa musi zostać połączona z regułami, uprawnieniami i historią procesu wewnątrz produktu.

Jeśli budujesz albo porządkujesz taki system, zobacz usługę B2B Operations Systems & Customer Portals lub opisz nam swój proces. Na pierwszej rozmowie wystarczy wskazać, co dziś jest wykonywane ręcznie i jaki wynik powinien wracać do systemu.