Integracja z białą listą MF zgłaszała zmianę konta, której nie było

Co dwa tygodnie, wcześnie rano, przychodzi ten sam mail: „Rejestr MF – zmiany u 6 klientów”. Zmienił się numer rachunku, brakuje adresu, coś do decyzji. Otwieramy pierwszą pozycję, potem drugą. Konto jest to samo co zawsze. Adres też. Zmieniło się tylko to, w jakiej kolejności rejestr podał rachunki.

Tak wyglądała nasza integracja z białą listą MF w pierwszej wersji. Technicznie działała bez zarzutu: pytała rejestry, porównywała dane, wysyłała raport. Tyle że raport był w większości szumem, a w jednym przypadku system nie tylko zgłaszał „zmianę”, ale po cichu podmieniał poprawny numer konta w karcie klienta na inny. Poniżej opisujemy trzy pułapki, przez które monitoring rejestrów zamienia się w generator fałszywych alarmów, i jak je zamknęliśmy w kodzie.

Kontekst: dane rozliczeniowe klientów, które mają się aktualizować same

W naszym CRM każda firma ma kartę z danymi z dwóch rejestrów państwowych. Z GUS (usługa BIR) bierzemy nazwę, REGON i adres. Z wykazu podatników VAT Ministerstwa Finansów, czyli tak zwanej białej listy, status VAT i numery rachunków bankowych. Te dane trafiają na faktury, więc muszą być aktualne.

Żeby nikt nie musiał tego klikać ręcznie, zadanie cykliczne odpala synchronizację raz na 14 dni. Porównuje to, co jest w CRM, z tym, co mówią rejestry, nanosi zmiany i wysyła zbiorczy raport mailem. Stawka jest konkretna: numer konta na fakturze to pieniądze, które mają trafić we właściwe miejsce, a raport, którego nikt nie czyta, bo zawsze jest w nim to samo, przestaje kogokolwiek chronić.

Objaw: „one po prostu zmieniają swoje miejsca”

Pierwszy sygnał był prosty: przy kilku firmach „zmiana rachunku” pojawiała się w każdym przebiegu. Komentarz, który padł przy przeglądaniu raportu, trafiał w sedno – rachunki się nie zmieniają, tylko zamieniają się miejscami. Gdy usiedliśmy do danych z ostatniego raportu, okazało się, że w sześciu pozycjach siedzą trzy zupełnie różne przyczyny.

Pułapka 1: rejestr zwraca listę w zmiennej kolejności

API białej listy zwraca dla firmy pole accountNumbers – listę wszystkich zgłoszonych rachunków. Firma z trzema kontami dostaje trzy numery. Kolejność tych numerów nie jest jednak stała: w jednym zapytaniu konto firmowe jest pierwsze, w kolejnym drugie.

Pierwsza wersja synchronizacji porównywała te listy element po elemencie. Dla kodu [A, B, C] i [C, A, B] to dwie różne listy, więc każdy przebieg kończył się „zmianą”. Gorzej: pole numeru konta w karcie klienta było wypełniane pierwszym rachunkiem z listy. Jeśli ktoś wcześniej świadomie wybrał w CRM konto, na które firma chce dostawać przelewy, synchronizacja zamieniała je na to, które rejestr akurat podał na początku. Dane poprawne zastępowała innymi danymi poprawnymi, ale tracąc wybór człowieka.

Pułapka 2: rejestr, który danej w ogóle nie publikuje

Druga grupa pozycji w raporcie wyglądała jak braki: „adres w rejestrze pusty, w CRM jest – do decyzji”. Dotyczyło to jednoosobowych działalności. Pierwsza myśl: coś nie tak z naszym zapytaniem do GUS. Sprawdziliśmy zapytanie, sprawdziliśmy pełny raport BIR dla trzech różnych numerów REGON. Zapytanie było poprawne. Adresu po prostu tam nie było.

GUS nie publikuje adresu działalności jednoosobowej, jeśli firma działa pod adresem zamieszkania właściciela. Pole jest puste także w pełnym raporcie. To nie jest brak danych do uzupełnienia, tylko informacja, której ten rejestr z założenia nie udostępnia.

Synchronizacja traktowała pusty rejestr jak sygnał „coś się zmieniło, zdecyduj”. Ponieważ stan rejestru się nie zmienia, te same firmy wracały do raportu co 14 dni, bez końca.

Pułapka 3: rejestr, który danej jeszcze nie ma

Trzeci przypadek: firma zarejestrowana kilka tygodni wcześniej. W CRM numer rachunku był, bo klient podał go przy współpracy. W wykazie MF rachunku jeszcze nie było, bo zgłoszenie nie zdążyło się tam pojawić. Rejestr pusty, CRM pełny – i znów pozycja w raporcie, choć dane w CRM były prawdziwe, a rejestr po prostu był w tyle.

Jeśli w Twojej firmie też coś „synchronizuje się samo” – faktury, płatności, dane klientów, stany magazynowe – i raporty z tego dawno przestały być czytane, warto to przejrzeć z kimś, kto buduje takie automatyzacje i integracje z rejestrami na co dzień.

Rozwiązanie: cztery zasady wpisane w kod synchronizacji

1. Rachunki porównujemy jako zbiór

Przed porównaniem zrzutu z poprzedniego przebiegu lista rachunków jest sortowana, a numer konta z CRM jest sprawdzany pod kątem tego, czy w ogóle występuje gdziekolwiek na liście z rejestru. Jeśli tak, zostaje – niezależnie od pozycji. Porównujemy same cyfry, więc zapis ze spacjami nie udaje innego konta:

konta_mf = {''.join(c for c in str(x) if c.isdigit())
            for x in (subject.get('accountNumbers') or [])}

konto_crm = ''.join(c for c in (klient.numer_konta or '') if c.isdigit())
if konto_crm and konto_crm in konta_mf:
    pass  # to samo konto, inna kolejność albo zapis - nic nie zmieniamy

2. Pusty rejestr nie jest zmianą

Jeśli rejestr nie ma wartości, a w CRM jest sensowna dana, dana w CRM zostaje i nie trafia do raportu. To stan normalny, a nie brak. Wyjątek to śmieci w rodzaju „none”, „null” czy pojedynczego myślnika, które kiedyś zostały w polach po imporcie – te synchronizacja dalej czyści.

3. Ta sama treść innym zapisem to nie zmiana

„ul. Szkolna 13” i „SZKOLNA 13” to ten sam adres. Przed porównaniem wartości są normalizowane, a jeśli po normalizacji są równe, zostaje wersja z CRM.

4. Pełny zrzut tylko raz

Komplet danych z rejestru trafia do maila tylko przy pierwszym pobraniu klienta. Później raport zawiera wyłącznie realne różnice. Do tego karta klienta w CRM dostała dwa osobne bloki, GUS i MF, z każdym polem opisanym osobno i statusem VAT pokazanym jako kolorowa plakietka. Widać od razu, skąd pochodzi która informacja.

Jak sprawdziliśmy poprawkę bez ryzyka

Synchronizacja ma tryb próbny, który nic nie zapisuje i nie wysyła maila, tylko wypisuje dla każdego klienta każde pole, które zostałoby zmienione, w formie „przed – po”. Zanim nowa wersja poszła na stałe, przepuściliśmy przez ten tryb całą bazę i sprawdziliśmy, czy z listy zniknęły fałszywe zmiany, a zostały prawdziwe.

Efekt

Raport co 14 dni zawiera tylko to, co faktycznie zmieniło się w rejestrach. Zniknęły zamiany kolejności rachunków, zniknęły jednoosobowe firmy bez publicznego adresu i świeże firmy, których rejestr jeszcze nie zna. Nie ma też cichych nadpisań numeru konta. Mail, który przychodzi, znowu jest wart przeczytania – a to jest jedyny powód, dla którego monitoring w ogóle istnieje.

To ta sama filozofia, którą stosujemy w automatycznym sprawdzaniu płatności faktur: automat ma odciążać człowieka, a nie dokładać mu pracy w postaci kolejnej listy do przejrzenia.

Jak sprawdzić u siebie: checklista integracji z rejestrem

• Czy porównujesz zbiory czy listy? Jeśli źródło nie gwarantuje kolejności, porównanie listy zawsze w końcu pokaże zmianę, której nie ma.
• Czy odróżniasz „brak danych” od „danych nie ma w źródle”? Pusty rejestr nie powinien kasować ani zgłaszać danych, które człowiek wpisał świadomie.
• Czy źródło zewnętrzne ma prawo nadpisać wybór człowieka? Przy rachunkach bankowych odpowiedź prawie zawsze brzmi: tylko gdy dotychczasowego konta nie ma już w rejestrze.
• Czy normalizujesz zapis przed porównaniem (wielkość liter, spacje, skróty typu „ul.”)?
• Czy masz tryb próbny, który pokaże każdą planowaną zmianę, zanim cokolwiek zapiszesz?
• Kiedy ostatnio ktoś przeczytał raport z synchronizacji do końca? Jeśli nie pamiętasz, raport najpewniej jest szumem.

Czego nauczyła nas ta historia

Integracja z zewnętrznym API ma trzy pułapki, które wyglądają jak zmiana danych, a nią nie są: niestabilna kolejność w kolekcjach, rejestr, który danej nie publikuje, i rejestr, który jeszcze jej nie ma. Od tej historii przy każdej integracji z rejestrem zaczynamy od pytania, czego to źródło nie wie, a dopiero potem od tego, co wie.

FAQ

Czy biała lista MF zwraca rachunki zawsze w tej samej kolejności?

W naszych przebiegach nie – ta sama firma potrafiła dostać listę rachunków w innej kolejności w kolejnych zapytaniach. Bezpieczniej traktować pole accountNumbers jako zbiór i nigdy nie zakładać, że pierwszy numer to konto główne.

Dlaczego GUS nie podaje adresu jednoosobowej działalności?

Gdy działalność jest prowadzona pod adresem zamieszkania właściciela, rejestr nie udostępnia tego adresu publicznie. Pole jest puste także w pełnym raporcie z usługi BIR, więc nie ma sensu szukać błędu w zapytaniu.

Co, jeśli firmy nie ma w wykazie podatników VAT?

API nie zwraca wtedy danych podmiotu ani rachunków. To nie jest awaria, tylko informacja o statusie VAT i tak warto ją zapisać w CRM. Pozostałe dane warto wtedy brać z GUS, a rachunek zostawić taki, jaki podał klient.

Czy synchronizacja z rejestrem powinna nadpisywać dane w CRM?

Dane rejestrowe tak, gdy rejestr ma wartość i jest ona realnie inna. Dane, które człowiek wybrał świadomie, jak konto do przelewów, tylko wtedy, gdy rejestr wyraźnie im przeczy – na przykład dotychczasowego konta nie ma już na liście.

Jak często warto synchronizować dane z białą listą?

Do bieżącej kontroli danych klientów w CRM wystarcza nam przebieg co 14 dni. Przed dużym przelewem do kontrahenta sprawdzenie rachunku w wykazie i tak warto zrobić w dniu płatności – to osobna, jednorazowa weryfikacja.