Właściciel firmy handlowej pokazał mi w czerwcu trzy monitory na jednym biurku. Na pierwszym sklep internetowy, na drugim program magazynowy, na trzecim księgowość. Między nimi siedziała pani Ewa i przepisywała zamówienia: ze sklepu do magazynu, z magazynu do faktury, z faktury do arkusza, w którym pilnowano płatności. Cztery godziny dziennie. „Nasze systemy ze sobą nie gadają” - powiedział i wzruszył ramionami, jakby to była pogoda. Zapytałem, czy pytał któregoś z dostawców o API. Spojrzał na mnie tak, jakbym zapytał po łacinie.
I to jest sedno problemu z integracjami w małej firmie 10 - 50 osób: nie brak technologii, tylko brak języka, żeby o nią zapytać. Prowadzę agencję AI i automatyzacji dla takich firm i wszystko, co radzę klientom, najpierw sprawdzam na sobie. W ostatnich miesiącach podłączałem program księgowy, giełdę ładunków, mapy dla ciężarówek i system reklamowy, u siebie i u klientów. Opowiem, co to „gadanie” naprawdę znaczy, co jest w środku, dlaczego psuje się akurat w piątek i o co zapytać dostawcę, zanim podpiszesz z nim cokolwiek. Bez żargonu. Z wpadkami, bo te uczą więcej niż sukcesy.
Spis treści
- Co naprawdę się dzieje, kiedy dwa programy „gadają”?
- Cztery sposoby gadania. Od kartki do telefonu
- Jak to wygląda w praktyce. Cztery integracje z ostatnich miesięcy
- Dlaczego integracja działa w czwartek, a w piątek już nie?
- O co zapytać dostawcę, zanim podpiszesz umowę
- Ile to kosztuje i ile trwa, uczciwie
- Kiedy lepiej zostawić przepisywanie
- Trzy rzeczy, które zabrałem z tych wdrożeń
- Słownik pojęć
Co naprawdę się dzieje, kiedy dwa programy „gadają”?
Wyobraź sobie, że każdy program w twojej firmie to urząd. Ma salę obsługi z ekranem, przyciskami i menu - to jest to, co widzisz ty i pani Ewa. Ale porządny urząd ma też drugie wejście, od podwórza, z okienkiem podawczym dla innych urzędów. Przy tym okienku wisi lista spraw, które da się tu załatwić: „wystaw fakturę”, „podaj zamówienia z dzisiaj”, „sprawdź, czy ten NIP jest aktywny”. Do każdej sprawy jest formularz z nazwanymi rubrykami, a odpowiedź też przychodzi w rubrykach, nie w wolnym tekście. To okienko to API.
Kiedy mówię, że dwa systemy gadają, mam na myśli dokładnie to: jeden program wypełnia formularz i podaje go do okienka drugiego, a drugi odpowiada. Bez człowieka, bez klikania, bez ekranu. Potrzebne są do tego cztery rzeczy i tylko cztery: adres okienka, przepustka, formularz w ustalonym kształcie i odpowiedź w ustalonym kształcie. Wszystko, co usłyszysz od informatyków o integracjach, da się sprowadzić do jednej z tych czterech rzeczy. Reszta to szczegóły wykonania.
Dlaczego nie da się po prostu „nauczyć programu klikania” w salę obsługi? Bo sala jest dla ludzi. Przyciski zmieniają miejsce po każdej aktualizacji, pojawia się wyskakujące okienko, ktoś przestawia kolumny. Program, który klika po ekranie, psuje się przy pierwszej zmianie wyglądu. Okienko podawcze jest stabilne z założenia, bo dostawca obiecał innym urzędom, że formularze się nie zmienią bez zapowiedzi. Ta obietnica jest warta więcej niż sam kod.
Czym to się różni od „kliknij eksport”?
Eksport do pliku to kartka wyniesiona z urzędu. Ktoś musi ją wziąć, zanieść do drugiego budynku i wrzucić do skrzynki. Dopóki robi to raz w tygodniu, działa. Przy codziennym przepisywaniu to pani Ewa z czterema godzinami. API to telefon między dwiema recepcjami: nikt niczego nie nosi, a rozmowa odbywa się tyle razy, ile trzeba. W małej firmie większość „integracji”, które kupuje się z dumą, to wciąż kartka, tylko ładniej opakowana. Warto wiedzieć, co się dostaje.
Co to jest klucz API i czemu nie wysyłam go mailem
Przepustka do okienka to ciąg znaków, który dostajesz od dostawcy. Kto go ma, ten jest tobą: może wystawić fakturę w twoim imieniu, pobrać listę klientów, zmienić ustawienia. Dlatego klucz traktuję jak hasło do konta bankowego: trzymam w sejfie, nie w mailu, nie w notatkach, nie w kodzie, który ktoś wrzuci na dysk. Kiedy w tym roku porządkowałem klucze do paneli hostingowych klientów, z dwudziestu ośmiu zapisanych działały trzy. Reszta wygasła albo została unieważniona, a nikt o tym nie wiedział. Przepustka ma termin ważności i ktoś musi o nim pamiętać.
Cztery sposoby gadania. Od kartki do telefonu
Nie każda integracja to to samo i nie każda potrzebuje najwyższego poziomu. U siebie i u klientów widzę cztery stopnie, i uczciwie: większość rzeczy, które działają najlepiej, siedzi na drugim i trzecim.
Pierwszy stopień to kartka. Eksport z jednego programu, import do drugiego, raz na tydzień albo raz na miesiąc. Zero kodu, zero umów. Śmieją się z tego informatycy, a ja nie. W sklepie, który uruchamiamy z partnerem, pierwsze setki produktów weszły z arkusza, nie przez API. Bo arkusz dało się przeczytać i poprawić w sobotę wieczorem, a na dokumentację okienka od dostawcy czekaliśmy.
Drugi stopień to pobieranie. Mój program co jakiś czas pyta cudzy: „co nowego?”. Giełda ładunków, mapy, kursy walut, biała lista podatników. Jedna strona pyta, druga odpowiada, nikt niczego nie zapisuje w cudzym systemie. Najbezpieczniejszy stopień, bo nawet jeśli coś pójdzie źle, to po mojej stronie.
Trzeci stopień to rozmowa w obie strony. Mój program nie tylko pyta, ale też zleca: „wystaw fakturę”, „dodaj produkt”, „oznacz zamówienie jako wysłane”. Tu zaczyna się odpowiedzialność, bo błąd w formularzu ląduje w cudzej bazie i czasem go nie cofniesz. Pisałem już, czego KSeF nie wybacza, i to jest dokładnie ten stopień.
Czwarty stopień to telefon od drugiej strony. Zamiast co pięć minut pytać „czy ktoś zapłacił?”, dajesz dostawcy swój numer i on dzwoni sam, gdy coś się wydarzy. Informatycy nazywają to webhookiem. Jest najszybszy i najelegantszy, ale wymaga, żebyś miał własny telefon włączony cały czas, czyli publiczny adres w sieci, który ktoś pilnuje. Dla małej firmy to często więcej utrzymania, niż warto. Sięgam po niego tylko tam, gdzie liczy się minuta: płatności, zamówienia ze sklepu.
Jak to wygląda w praktyce. Cztery integracje z ostatnich miesięcy
Teoria jest ładna, ale „gadanie” rozumie się dopiero na konkretach. Cztery z tego roku, od najprostszej do tej, która kosztowała mnie najwięcej cierpliwości.
Faktury: program księgowy i biała lista Ministerstwa Finansów
Najprostsza integracja, jaką kiedykolwiek zrobiłem, i najwięcej mi dała. Dwa okienka: mój program księgowy, który przyjmuje „wystaw fakturę”, i rejestr Ministerstwa Finansów, który odpowiada na „czy ten NIP jest aktywny i na jakie konto płacić”. Oba mają publiczną dokumentację, oba dają dostęp bez umów i spotkań z handlowcem. Nakładka, która pobiera dane z oferty, sprawdza NIP i składa fakturę, powstała w dwa wieczory. Z pół dnia klikania w miesiącu zostało jedno świadome kliknięcie „wyślij”. Całość opisałem osobno w tekście o fakturach, które wystawiają się same. Tu ważny jest wniosek: kiedy obie strony mają otwarte okienko, integracja to dwa wieczory, nie projekt.
Giełda ładunków: czekanie na papier, nie na kod
Firma transportowa, z którą pracuję, chciała widzieć w swoim systemie ładunki z giełdy transportowej, bez przeklejania ich ręcznie przez spedytora. Giełda ma API. Ale ma też umowę, opłatę aktywacyjną, środowisko testowe z fikcyjnymi ofertami, a potem coś, co dostawca nazywa zatwierdzeniem biznesowym, i dopiero po nim przełączenie na prawdziwe dane. Sam kod to pytanie: „pokaż ładunki z punktu A do punktu B z ostatnich ośmiu godzin”. Okienko oddaje najwyżej trzydzieści ofert naraz i nie pozwala pytać o obszar większy niż 200 km. Oferty przychodzą anonimowe; kontakt do zleceniodawcy dostajesz dopiero drugim pytaniem, osobno dla każdej.
Teraz wpadka. Mail od opiekuna z giełdy, że konto zostało przełączone na produkcję, leżał w skrzynce miesiąc bez odpowiedzi. Przez ten miesiąc testowaliśmy na sali treningowej i zastanawialiśmy się, czemu to tak długo trwa, a abonament liczył się od dnia przełączenia. Sprawdzaliśmy wszystko, tylko nie skrzynkę, do której przyszła odpowiedź. Kiedy w końcu przełączyliśmy, pierwsze prawdziwe pytanie o trasę z bazy klienta do Berlina zwróciło 27 ofert. Kod działał od tygodni. Czekaliśmy na papier i na własną nieuwagę.
Druga lekcja z tej samej integracji: jedna z firm, do której pobraliśmy kontakt, miała w ofercie tylko numer telefonu. Żadnego maila. Automat, który miał wysyłać propozycje, musi mieć plan B na taki przypadek, bo inaczej po cichu pominie klienta i nikt się nie dowie.
Trasa dla ciężarówki: mapa, która zna wysokość wiaduktów
Ten sam klient potrzebował wyceny trasy, zanim spedytor odbierze telefon. Okienko od map wybrałem nie po marce, tylko po tym, co umie: trasa dla pojazdu o konkretnej masie i wysokości, z zakazami wjazdu, promami i tunelami. Popularne mapy dla kierowców osobówek tego nie oddają. Budowa zajęła trzy dni, z czego połowę pochłonęło sprawdzanie na znanych trasach, czy wyniki pokrywają się z tym, co spedytor zna z praktyki. Dostawca daje spory darmowy limit zapytań, który małej firmie wystarcza z zapasem. Szczegóły są w tekście o kalkulatorze frachtu. Wniosek dla ciebie: przy wyborze dostawcy czytaj listę spraw przy okienku, nie reklamę.
Rekrutacja kierowców i system reklamowy
Najmniej oczywista z czterech. Firma rekrutująca kierowców zbiera zgłoszenia z reklam w mediach społecznościowych, a rekruter w panelu oznacza, kto został zatrudniony. Zatrudnienie to jedyny wynik, który ma dla niej wartość. Podłączyliśmy więc panel do okienka systemu reklamowego tak, żeby po oznaczeniu „zatrudniony” leciało tam zgłoszenie: ten kandydat się udał. System reklamowy uczy się wtedy szukać ludzi podobnych do zatrudnionych, a nie do tych, którzy tylko kliknęli.
Dane osobowe nie wychodzą z firmy w czytelnej postaci. Zanim mail i telefon trafią do okienka, zamieniamy je w odcisk palca: ciąg znaków, z którego nie da się odtworzyć nazwiska, ale który po drugiej stronie pozwala rozpoznać tę samą osobę. Uczciwie dodam, co mnie zaskoczyło: to samo okienko odpowiadało „brak uprawnień”, gdy pytałem je o dane, a przyjmowało zgłoszenia bez protestu. Dokumentacja mówiła jedno, rzeczywistość drugie. Gdybym uwierzył pierwszemu komunikatowi błędu, integracja nigdy by nie powstała. Testuj zamiast zakładać.
Dlaczego integracja działa w czwartek, a w piątek już nie?
To pytanie dostaję najczęściej i jest najważniejsze w całym tekście, bo o budowaniu integracji napiszą ci wszyscy, a o tym, czemu umierają, prawie nikt. Z moich wdrożeń wychodzi kilka powtarzalnych powodów.
Przepustka wygasła. Klucze mają termin ważności, bywają unieważniane przy zmianie hasła, przy zmianie osoby, która je wystawiła, przy aktualizacji planu u dostawcy. Program nie wie, że przepustka jest nieważna, dopóki nie podejdzie do okienka. A kiedy podejdzie i dostanie odmowę, często zapisze błąd w pliku, którego nikt nie czyta.
Dostawca przestawił okienko. Zmienił formularz, dodał rubrykę, wycofał jedną z opcji. Przy ustawianiu kampanii reklamowej dla klienta cały zapis był odrzucany, bo jedno z miejsc wyświetlania reklam zostało po cichu wycofane. Dobrzy dostawcy zapowiadają takie zmiany mailem z wyprzedzeniem. Pytanie, czy ktoś u ciebie ten mail czyta.
Trafiłeś w limit. Okienko giełdy oddaje trzydzieści ofert naraz i tylko z ośmiu ostatnich godzin. W nocy z soboty na niedzielę pytanie o ładunki z Niemiec zwraca zero. To nie jest awaria, tylko puste okienko, ale program, który nie rozróżnia „nic nie ma” od „nie działa”, będzie cię straszył alarmami albo, gorzej, milczał, gdy naprawdę padnie.
Nowa wersja twojego programu zgubiła ustawienia. Ta zabolała mnie najbardziej. Przy wgrywaniu kolejnej wersji systemu dla klienta nie przeniosły się dane dostępowe do giełdy. Wszystko inne działało. Giełda była martwa i nikt tego nie zauważył, dopóki ktoś nie wszedł w tę zakładkę. Od tamtej pory każda integracja ma u mnie czujnik: osobny automat, który raz na jakiś czas zadaje okienku proste pytanie i krzyczy, gdy nie dostanie odpowiedzi. Pisałem już, że proces bez czujnika nie jest skończony, i integracje są tego najlepszym przykładem.
Okienko jest, ale tylko w budynku. Dostawca systemu telematycznego odpowiedział klientowi, że API działa, i owszem, działa, tylko na serwerze stojącym w firmie, w sieci lokalnej, niedostępnej z zewnątrz. Żeby mój program mógł tam zapukać, trzeba zbudować bezpieczny tunel, a zmiana sposobu wystawienia okienka jest u dostawcy płatna. Technicznie to wciąż integracja. Praktycznie to osobny projekt.
Okienko istnieje na papierze. Kupiłem kiedyś dostęp do API banku zdjęć, a potem miesiąc czekałem na odpowiedź supportu, bo okienko oddawało co innego, niż obiecywała dokumentacja. Dostawca może mieć API w cenniku i nie mieć nikogo, kto je rozumie.
O co zapytać dostawcę, zanim podpiszesz umowę
Z tych wszystkich wpadek ułożyłem listę pytań. Zadaję je dziś przy każdym nowym narzędziu, zanim ktokolwiek napisze linijkę kodu, i radzę to samo klientom. Zadaj je przed podpisaniem, bo po podpisaniu dostawca ma dużo mniej powodów, żeby odpowiadać.
- Czy macie API i czy dokumentacja jest publiczna? Jeśli żeby zobaczyć listę spraw przy okienku, musisz najpierw podpisać umowę o poufności, to czerwone światło. Dobrzy dostawcy wystawiają dokumentację na stronie.
- Co dokładnie da się przez to zrobić? Tylko czytać dane czy też zapisywać? Są narzędzia, które oddają listę klientów, ale nie pozwalają dodać nowego. Wtedy masz pół integracji.
- Ile kosztuje dostęp? Osobny abonament, opłata aktywacyjna, limity zapytań w cenie, dopłaty powyżej. Giełda ładunków liczy za to osobno od programu, w którym spedytor klika. Nie każdy o tym mówi na pierwszym spotkaniu.
- Czy jest środowisko testowe? Sala treningowa z fikcyjnymi danymi, na której można się pomylić bez konsekwencji. Przy integracjach, które zapisują coś w cudzym systemie, bez niej nie zaczynam.
- Jak długo żyje klucz i jak go odnowić? Oraz: kto u was wystawia nowy, gdy stary wygaśnie w sobotę.
- Jak zapowiadacie zmiany okienka? Mail, strona ze zmianami, nic. „Nic” też jest odpowiedzią i warto ją usłyszeć wprost.
- Kto odpowiada na pytania techniczne i w jakim czasie? Osoba czy formularz, dzień czy miesiąc. Bank zdjęć nauczył mnie pytać o to na początku.
- Czy wyciągnę swoje dane w całości, kiedy odejdę? To pytanie o wyjście z relacji. Dostawca, który na nie krzywo patrzy, mówi ci coś ważnego o sobie.
Właściciel firmy handlowej z początku tego tekstu zadał w lipcu te pytania trzem swoim dostawcom. Dwaj mieli okienko od lat, tylko nikt nigdy nie zapytał. Trzeci nie miał i nie planował. Ta jedna rozmowa ustaliła, w jakiej kolejności cokolwiek u niego ruszamy.
Ile to kosztuje i ile trwa, uczciwie
Powiem coś, czego nie usłyszysz w ofercie na integrację: kod jest najmniejszą częścią kosztu. Gdy patrzę na swoje wdrożenia z ostatnich miesięcy, czas rozkłada się z grubsza tak: czytanie dokumentacji i testy przy okienku to jakieś 40 procent, samo pisanie 20, a pozostałe 40 to czekanie na dostawcę, umowy, dostępy i wyjaśnianie, czemu coś odpowiada inaczej, niż obiecano. Faktury: dwa wieczory. Mapa dla ciężarówek: trzy dni. Reklamy: jedno popołudnie kodu i tydzień sprawdzania, czy zgłoszenia naprawdę dochodzą. Giełda: kilka dni kodu rozciągnięte na miesiące papieru.
Po stronie dostawców rozstrzał jest ogromny. Rejestr podatników i mapy w darmowym limicie kosztują zero. Giełda ma własny, stały abonament za samo okienko, niezależny od tego, ile z niego korzystasz. Są narzędzia, które liczą za każde pytanie, i wtedy program pytający co minutę „czy ktoś zapłacił?” potrafi zaskoczyć fakturą. Dlatego pytanie o cenę dostępu stoi na mojej liście tak wysoko.
I jest koszt, który prawie nikt nie wpisuje do tabelki: utrzymanie. Każda integracja to kolejne okienko, które może się zmienić, kolejna przepustka z terminem, kolejny czujnik do pilnowania. Liczę to u siebie jako stały podatek, kilka godzin w miesiącu na wszystkie naraz, i doliczam do każdej wyceny. Jak uczciwie policzyć zwrot z automatyzacji razem z tym podatkiem, opisałem osobno. Integracja bez budżetu na utrzymanie to integracja z terminem przydatności.
Kiedy lepiej zostawić przepisywanie
Mógłbym sprzedać integrację każdemu, kto ma dwa programy. Nie robię tego, bo w kilku sytuacjach kartka jest po prostu lepsza.
Gdy przenosisz dane rzadziej niż raz w tygodniu i zajmuje ci to mniej niż godzinę. Eksport i import wygrywają z każdą integracją, bo nie mają przepustek, limitów i czujników. Pani Ewa z czterema godzinami dziennie to zupełnie inna sprawa niż księgowa z kwadransem w miesiącu.
Gdy dostawca nie ma okienka i nie planuje go mieć. Wtedy kusi zbudowanie programu, który udaje człowieka i klika po ekranie. Widziałem takie protezy u klientów i odradzam: pękają przy każdej aktualizacji wyglądu, a naprawy kosztują więcej niż samo przepisywanie. Jeśli narzędzie nie umie gadać, lepszym pomysłem jest wymiana narzędzia przy najbliższej okazji niż protezy wokół niego.
Gdy jedno z narzędzi i tak chcesz wymienić w tym roku. Integracja z programem, który odchodzi, to pieniądze wyrzucone w błoto, nawet jeśli działa pięknie.
I gdy dane w jednym z systemów są bałaganem. Integracja nie sprząta, integracja przenosi. Zdublowani klienci, produkty bez kodów, ceny w trzech wersjach: automat rozniesie to po wszystkich systemach szybciej, niż ktokolwiek zauważy. Dlatego w mojej checkliście wyboru pierwszego procesu jakość danych wejściowych ma osobne pytanie. Najpierw porządek, potem telefon między recepcjami.
Trzy rzeczy, które zabrałem z tych wdrożeń
Pierwsza: „gadanie” to nie magia, tylko okienko, przepustka, formularz i odpowiedź. Kiedy właściciel firmy to rozumie, przestaje być zakładnikiem informatyka i dostawcy, bo umie zadać osiem pytań i zrozumieć odpowiedzi. To zmienia układ sił bardziej niż jakakolwiek technologia.
Druga: najdłużej trwa papier i czekanie, nie kod. Miesiąc z nieprzeczytanym mailem od giełdy nauczył mnie więcej o integracjach niż wszystkie dokumentacje razem. Zacznij od pytań do dostawcy, nie od programisty.
Trzecia: integracja bez czujnika umiera w ciszy. Giełda martwa po aktualizacji, bo zgubiły się ustawienia, nie była winą dostawcy ani kodu. Była winą braku kogoś, kto raz dziennie zapukałby do okienka i sprawdził, czy ktoś odpowiada.
Nie potrzebujesz do tego działu IT. Potrzebujesz listy programów, których używasz, ośmiu pytań z tego tekstu i jednej uczciwej rozmowy o tym, gdzie w twojej firmie siedzi pani Ewa z trzema monitorami.
Słownik pojęć
- API - „okienko podawcze” programu dla innych programów. Lista spraw, które da się załatwić bez klikania w ekran, z formularzem i odpowiedzią w ustalonym kształcie.
- Klucz API - przepustka do okienka. Ciąg znaków, który identyfikuje twoją firmę; kto go ma, działa w twoim imieniu. Ma termin ważności.
- Dokumentacja API - opis listy spraw, formularzy i odpowiedzi. Powinna być publiczna; jej brak lub ukrycie za umową to sygnał ostrzegawczy.
- Środowisko testowe (sandbox) - sala treningowa dostawcy z fikcyjnymi danymi, na której można testować bez konsekwencji. Osobne od produkcji, często z osobną przepustką.
- Limit zapytań - ile razy i jak dużo można pytać okienko w danym czasie. Przekroczenie to odmowa, nie awaria.
- Webhook - telefon od drugiej strony: zamiast pytać co chwilę, dajesz dostawcy swój adres, a on sam zgłasza zdarzenie, gdy nastąpi.
- Hash (odcisk palca danych) - ciąg znaków wyliczony z maila czy telefonu, z którego nie da się odtworzyć oryginału, ale który pozwala rozpoznać tę samą osobę po drugiej stronie.
- Czujnik integracji (healthcheck) - osobny automat, który regularnie zadaje okienku proste pytanie i alarmuje, gdy nie dostaje odpowiedzi.
Przyślij mi listę programów, z których korzystasz. Powiem ci, które już umieją gadać
Jeśli w twojej firmie ktoś przepisuje dane między dwoma ekranami i nikt nie wie, czy to w ogóle da się połączyć, napisz do mnie na [email protected]. Wystarczy lista narzędzi, z których korzystasz. Sprawdzę, które mają okienko, które mają je tylko na papierze, i od którego połączenia zacząć, żeby zwróciło się najszybciej. Bez pisania kodu na tym etapie, bo kod to i tak najmniejsza część.
Jeśli wolisz najpierw zobaczyć, jak wygląda współpraca ze mną, od pierwszej rozmowy po wdrożenie, opisałem to osobno.
własnej firmie cybulski.ai JC
