Integracja aplikacji dedykowanej z Bitrix24 i ERP — jak to zrobić dobrze

Zacznij od mapy danych, nie od API

Zanim ktokolwiek dotknie dokumentacji API, warto wypisać encje, które krążą po firmie: klient, oferta, zamówienie, zlecenie, faktura, płatność. Dla każdej z nich odpowiadamy na trzy pytania: gdzie powstaje, kto ją zmienia i który system jest jej źródłem prawdy.

Bez tej mapy integracja zamienia się w zbiór punktowych połączeń, których nikt po roku nie potrafi odtworzyć. Z mapą — staje się kilkoma jasnymi przepływami, które da się testować i monitorować osobno.

• Jedna encja = jedno źródło prawdy. Reszta systemów tylko czyta lub uzupełnia własne pola.
• Każdy przepływ ma kierunek: z aplikacji do CRM, z CRM do aplikacji, albo dwukierunkowy z regułą rozstrzygania konfliktów.
• Każde pole ma właściciela — inaczej dwa systemy będą się wzajemnie nadpisywać.

Bitrix24 w praktyce: leady, deale, kontakty i firmy

Bitrix24 udostępnia REST API, do którego najprościej podłączyć się przez webhook przychodzący. Z perspektywy aplikacji dedykowanej najczęściej używa się kilku metod: tworzenia i aktualizacji deali, kontaktów oraz firm, a także zapisów w osi czasu, żeby handlowiec widział kontekst bez wychodzenia z CRM.

Kluczowa decyzja projektowa dotyczy tego, czy zgłoszenie ląduje jako lead, czy od razu jako deal w konkretnym lejku i na konkretnym etapie. Dla firm, które pracują lejkiem sprzedażowym i nie używają modułu leadów, tworzenie deala od razu jest zwykle prostsze operacyjnie — pod warunkiem, że aplikacja poprawnie podepnie kontakt i firmę oraz obsłuży deduplikację.

• Deduplikacja po e-mailu i telefonie przed utworzeniem nowego rekordu.
• Świadomy wybór lejka i etapu początkowego zamiast domyślnego ustawienia systemu.
• Zapis pełnego kontekstu zgłoszenia w komentarzu i osi czasu, nie tylko w polach standardowych.
• Mapowanie pól niestandardowych po ich identyfikatorach, nie po nazwach widocznych w interfejsie.

ERP: gdzie zwykle leży prawdziwa trudność

Integracja z ERP bywa trudniejsza niż z CRM, bo systemy ERP częściej działają lokalnie, mają ograniczone API albo wymagają wymiany plików. Zamiast walczyć z tym na siłę, warto rozdzielić przypadki: dane, które muszą być dostępne natychmiast, i dane, które mogą synchronizować się cyklicznie.

Stany magazynowe czy dostępność towaru zwykle wystarczy odświeżać co kilka-kilkanaście minut. Dokumenty sprzedażowe i płatności można przenosić paczkami. Natychmiastowa synchronizacja jest potrzebna rzadziej, niż się początkowo wydaje, a kosztuje wielokrotnie więcej.

Odporność integracji: błędy, ponawianie i idempotencja

Każda integracja kiedyś dostanie timeout, limit zapytań albo odpowiedź, której się nie spodziewa. Różnica między integracją profesjonalną a prowizoryczną polega na tym, co się wtedy dzieje: czy dane giną po cichu, czy trafiają do kolejki i są ponawiane.

Praktyczny standard to kolejka zadań z ponawianiem, klucz idempotencji przy tworzeniu rekordów (żeby ponowienie nie utworzyło drugiego deala) oraz dziennik wszystkich wywołań z możliwością podglądu, co dokładnie zostało wysłane i co wróciło.

• Kolejka i ponawianie z rosnącym odstępem zamiast pojedynczej próby wysyłki.
• Klucz idempotencji, żeby ponowienie nie tworzyło duplikatów w CRM.
• Dziennik integracji dostępny dla zespołu, nie tylko w logach serwera.
• Alert do osoby odpowiedzialnej, gdy błędy przekroczą ustalony próg.

Bezpieczeństwo i dostępy

Webhook przychodzący do CRM to w praktyce klucz do danych firmy — powinien być przechowywany jako sekret po stronie serwera, nigdy w kodzie frontendu ani w repozytorium. Warto też ograniczyć zakres uprawnień webhooka wyłącznie do metod, których aplikacja faktycznie używa.

Po stronie ERP obowiązuje ta sama zasada minimalnych uprawnień: osobne konto techniczne dla integracji, dostęp tylko do potrzebnych obiektów i możliwość odcięcia go bez wpływu na pracę ludzi.

Kolejność wdrożenia, która się sprawdza

Najbezpieczniejszy schemat to trzy etapy. Najpierw jeden przepływ jednokierunkowy o największej wartości — zwykle zgłoszenie z aplikacji do CRM. Potem odczyt danych z CRM lub ERP do aplikacji, żeby zespół nie musiał przełączać systemów. Dopiero na końcu przepływy dwukierunkowe, tam gdzie naprawdę są potrzebne.

Taki podział pozwala uruchomić realną wartość po kilku dniach zamiast po kilku miesiącach i daje czas na obserwację, jak dane zachowują się w praktyce, zanim skomplikujemy architekturę.

• Etap 1: zgłoszenia i zamówienia z aplikacji do CRM, jednokierunkowo.
• Etap 2: odczyt statusów, cennika lub stanów magazynowych do aplikacji.
• Etap 3: wybrane przepływy dwukierunkowe z jasną regułą rozstrzygania konfliktów.

Jak policzyć, czy integracja się opłaca

Najprostsza miara to liczba ręcznych przepisań danych dziennie pomnożona przez średni czas jednego przepisania i koszt godziny pracy. Do tego dochodzi koszt błędów: źle przepisany NIP, adres dostawy czy kwota to nie tylko poprawka, ale często reklamacja lub korekta faktury.

Warto zmierzyć te wartości przed integracją, bo po wdrożeniu znikają tak szybko, że nikt nie pamięta, ile kosztowały. Bez punktu odniesienia trudno uzasadnić kolejne etapy rozwoju.