Co to jest warstwa API w systemie firmowym

Warstwa API to część systemu firmowego, przez którą inne programy mogą w uporządkowany sposób pobierać z niego dane i zlecać mu operacje – bez zaglądania do bazy danych i bez klikania w ekrany. Można o niej myśleć jak o okienku podawczym w urzędzie: nie wchodzisz na zaplecze, nie przeglądasz segregatorów, tylko składasz wniosek na ustalonym formularzu i dostajesz odpowiedź w ustalonej formie. Poniżej wyjaśniamy to bez technicznego żargonu, pokazujemy przykłady z codziennej pracy firmy i podpowiadamy, o co zapytać dostawcę oprogramowania.

API w jednym zdaniu i w jednym obrazku

API (Application Programming Interface) to zestaw reguł, według których jeden program rozmawia z drugim. Reguły określają:

• co można zapytać lub zlecić – np. „podaj stan magazynowy produktu”, „utwórz zamówienie”, „zwróć listę faktur klienta”,
• w jakiej formie – jakie pola trzeba podać i w jakim formacie przyjdzie odpowiedź,
• kto może to zrobić – który program lub użytkownik ma do tego prawo,
• co się dzieje przy błędzie – jaki komunikat wraca, gdy danych brakuje albo operacja jest niedozwolona.

„Warstwa” oznacza, że API jest osobnym piętrem aplikacji. Na dole leży baza danych, w środku logika biznesowa (reguły cen, rabatów, statusów), a na górze różne „wejścia”: ekrany dla pracowników, portal dla klientów, aplikacja mobilna i właśnie API dla innych systemów. Wszystkie wejścia korzystają z tej samej logiki w środku, więc cena policzona w portalu jest taka sama jak cena wysłana do partnera.

Jak to wygląda w życiu firmy – przykłady

Większość właścicieli firm korzysta z API codziennie, nawet o tym nie wiedząc. Kilka typowych sytuacji:

1. Klient składa zamówienie w portalu B2B, a po chwili pojawia się ono w systemie ERP. Portal nie wpisuje danych do ERP „ręką robota” – wysyła zamówienie przez API albo przez usługę, która z API korzysta.
2. Sklep pokazuje aktualny stan magazynu. Co kilka minut pyta system magazynowy o zmiany i dostaje listę produktów z nowymi ilościami.
3. Kurier nadaje numer przesyłki. System wysyłek przekazuje dane paczki do przewoźnika i odbiera numer listu przewozowego oraz etykietę.
4. Formularz na stronie tworzy leada w CRM. Strona wysyła dane kontaktowe do CRM, a ten zakłada kartę firmy i zadanie dla handlowca.
5. Dystrybutor pobiera Twój katalog. Zamiast co miesiąc dostawać arkusz mailem, jego system sam pobiera aktualne produkty, ceny i zdjęcia.

W każdym z tych przykładów człowiek nie przepisuje danych, a system po drugiej stronie nie musi znać wnętrza Twojej aplikacji. Zna tylko „formularz” w okienku.

Dlaczego nie połączyć systemów bezpośrednio przez bazę?

To pytanie pada często, bo połączenie „baza do bazy” wydaje się szybsze. W praktyce ma trzy poważne wady:

• Omija reguły biznesowe. Zapisując zamówienie wprost do tabeli, pomijamy numerację, rezerwację towaru i przeliczenia, których pilnuje aplikacja.
• Jest kruche. Każda aktualizacja jednego systemu może zmienić strukturę tabel i po cichu zepsuć połączenie.
• Daje za duży dostęp. Kto ma dostęp do bazy, widzi wszystko – także dane, których partner czy inny program w ogóle nie potrzebuje.

Warstwa API rozwiązuje te problemy: jest stabilnym kontraktem, który nie zmienia się przy każdej przebudowie aplikacji, i wydaje tylko to, co jest potrzebne.

Z czego składa się dobra warstwa API

Nie trzeba znać szczegółów technicznych, ale warto wiedzieć, jakie elementy powinny się w niej znaleźć – to pomaga ocenić ofertę dostawcy.

• Zasoby i operacje – czytelnie nazwane obiekty (produkty, klienci, zamówienia) i operacje na nich.
• Uwierzytelnienie i uprawnienia – każdy program łączy się własnym kluczem, a system wie, co wolno danemu kluczowi. W B2B uprawnienia sięgają często poziomu konkretnego klienta: dystrybutor widzi tylko swoje ceny i swoje zamówienia.
• Walidacja – API odrzuca niekompletne lub błędne dane z jasnym komunikatem, zamiast zapisywać byle co.
• Wersjonowanie – gdy API się zmienia, stara wersja działa jeszcze przez jakiś czas, żeby partnerzy zdążyli się dostosować.
• Dokumentacja – opis, z którego inny programista zrozumie, jak się połączyć, bez spotkań i maili.
• Logi i limity – zapis, kto i kiedy o co pytał, oraz ograniczenie liczby zapytań, żeby jeden źle napisany program nie przeciążył systemu.

API jako pierwszy krok modernizacji

Warstwa API bywa też sposobem na odświeżenie starego systemu bez wyłączania go. Przed starą aplikację stawia się nową warstwę API, a nowy portal, aplikacja mobilna czy integracje łączą się już tylko z nią. Za tą „fasadą” można potem stopniowo wymieniać stare moduły – użytkownicy i partnerzy nie zauważą zmiany, bo okienko zostaje to samo. Kiedy taki wariant jest lepszy od przepisania całości, opisujemy w artykule Modernizacja backendu – kiedy przepisać system.

Kiedy API daje firmie największą wartość

Warstwa API zaczyna się opłacać, gdy:

• te same dane są potrzebne w kilku miejscach (ERP, sklep, portal, CRM, raporty),
• ktoś w firmie regularnie przepisuje dane z jednego programu do drugiego,
• partnerzy proszą o automatyczny dostęp do katalogu, cen lub statusów zamówień,
• planujesz nowy front – portal klienta, aplikację mobilną – i nie chcesz budować go na starym kodzie.

Od której integracji zacząć i jak policzyć czas ręcznej pracy, podpowiadamy w tekście Integracje API w firmie – od czego zacząć.

Pytania, które warto zadać dostawcy

Jeśli rozmawiasz z software housem albo dostawcą gotowego systemu, poniższe pytania szybko pokażą, jak dojrzałe jest ich API:

1. Czy API jest udokumentowane i czy mogę zobaczyć dokumentację przed podpisaniem umowy?
2. Jakie dane i operacje są dostępne – tylko odczyt czy także zapis (np. zamówienia, klienci)?
3. Jak działają uprawnienia – czy mogę dać partnerowi dostęp tylko do jego danych?
4. Co się stanie, gdy API się zmieni – jak długo działa poprzednia wersja i jak dowiem się o zmianie?
5. Czy są limity zapytań, a jeśli tak, to jakie i czy dodatkowo płatne?
6. Gdzie widać logi – czy zobaczę, że integracja przestała działać, zanim zadzwoni klient?
7. Czy system może sam powiadomić inny program o zmianie (tzw. webhook), czy trzeba go ciągle odpytywać?
8. Kto utrzymuje integracje po wdrożeniu i jak wygląda reakcja na awarię?

Jeśli odpowiedź na większość pytań jest ogólnikowa, integracje prawdopodobnie będą wymagały obejść. Szczególnie przy połączeniach z zewnętrznymi firmami – o tym, jak ograniczyć błędy danych w wymianie z partnerami, piszemy w osobnym artykule o integracjach z partnerami.

Następny krok

Weź kartkę i wypisz programy, z których korzysta Twoja firma, a strzałkami zaznacz, między którymi ludzie przenoszą dane ręcznie. To wystarczy, żeby zobaczyć, gdzie warstwa API najbardziej by pomogła. Jeśli chcesz przejść przez taką mapę z kimś, kto na co dzień projektuje integracje API i automatyzację, napisz do nas – podpowiemy, od czego zacząć i czy Twoje systemy mają już API, z którego da się skorzystać.