API co to jest: definicja na przykładach NBP, GUS i białej listy VAT, REST API, webhook, OpenAPI, klucze API i bezpieczeństwo integracji.

„Mamy do tego API” — to zdanie słyszy każdy, kto rozmawia z programistami albo z dostawcą oprogramowania. API co to jest? Najkrócej: API (application programming interface, interfejs programowania aplikacji) to ustalony sposób, w jaki jeden program prosi drugi o dane albo o wykonanie czynności — bez udziału człowieka, bez klikania w ekrany i bez przepisywania danych z jednego okna do drugiego.
Ten tekst jest dla właścicieli firm i menedżerów, którzy chcą rozumieć, o czym mówią ich programiści, na tyle dobrze, żeby zadać właściwe pytania. Zaczynamy od przykładów z życia polskiej firmy, potem przechodzimy do pojęć, które padają w każdej rozmowie o integracji: REST API, webhook, OpenAPI, klucz API. Każda definicja ma link do źródła, które ją ustanawia — dokumentacji, specyfikacji albo standardu.
Najłatwiej zrozumieć API na trzech usługach, z których korzysta wiele polskich firm, często nie wiedząc, że robi to przez API.
Kurs walut z NBP. Program księgowy, który sam wpisuje kurs euro z tabeli NBP do faktury walutowej, nie otwiera strony banku. Wysyła zapytanie do serwisu api.nbp.pl, który — jak opisuje go NBP — „udostępnia publiczne Web API umożliwiające klientom HTTP wykonywanie zapytań” na zbiorach danych o kursach walut i cenach złota, aktualnych i archiwalnych.
Dane firmy z GUS. Formularz, który po wpisaniu NIP sam uzupełnia nazwę i adres kontrahenta, zwykle pobiera je z rejestru REGON. GUS udostępnia go przez usługę BIR1 (Baza Internetowa REGON 1) — usługę sieciową, w której można wyszukiwać po numerze REGON, NIP albo KRS.
Biała lista VAT. Przed zapłatą większej faktury firma może automatycznie sprawdzić, czy kontrahent jest czynnym podatnikiem VAT i czy numer konta jest na wykazie. Ministerstwo Finansów udostępnia do tego API Rejestr WL — z zapytaniem o podatnika po NIP i o to, czy dany rachunek bankowy należy do danego NIP.
We wszystkich trzech przypadkach schemat jest ten sam: jeden program (klient) wysyła zapytanie w ustalonym formacie, drugi (serwer) odsyła odpowiedź, też w ustalonym formacie. API to właśnie ta umowa — jakie zapytania można wysłać, jakich danych potrzebują i co wróci w odpowiedzi.
Tak wygląda to w praktyce. Poniżej zapytanie o bieżący średni kurs euro, wykonane 30 września 2026 roku według wzorów zapytań opublikowanych na api.nbp.pl, i odpowiedź serwera w formacie JSON:
1GET https://api.nbp.pl/api/exchangerates/rates/a/eur/?format=json
1{"table":"A","currency":"euro","code":"EUR","rates":[{"no":"190/A/NBP/2026","effectiveDate":"2026-09-30","mid":4.3672}]}
Nie trzeba umieć programować, żeby to przeczytać: tabela A, waluta euro, numer tabeli, data i kurs średni 4,3672 zł. Program księgowy robi dokładnie to samo, tylko sam wstawia liczbę we właściwe pole.
Kiedy programista mówi „mamy REST API”, ma na myśli API zbudowane według określonego stylu architektury. Termin REST (Representational State Transfer) wprowadził Roy Fielding w rozprawie doktorskiej z 2000 roku. W rozdziale 5 wyprowadza go krok po kroku, dokładając kolejne ograniczenia do systemu, który na początku nie ma żadnych.
„RESTful API” to po prostu API, które stosuje się do tych zasad. W codziennym użyciu oba określenia — REST API i RESTful API — znaczą to samo: API dostępne przez HTTP, w którym zasoby mają adresy, a operacje wykonuje się standardowymi metodami HTTP. Wiele API nazywanych REST-owymi nie spełnia wszystkich sześciu warunków co do joty, szczególnie tego o hipermediach. Dla firmy, która z nich korzysta, nie ma to zwykle znaczenia — liczy się, czy API jest dobrze opisane i przewidywalne.
W REST API to metoda HTTP mówi serwerowi, co ma zrobić z zasobem. Znaczenie metod ustala standard HTTP, dziś w wersji RFC 9110:
Dla biznesu najważniejsze jest jedno pojęcie z tego standardu: idempotentność. RFC 9110 definiuje ją tak: metoda jest idempotentna, „if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request” — „jeśli zamierzony skutek wielu identycznych zapytań tą metodą jest dla serwera taki sam jak skutek jednego takiego zapytania” (tłumaczenie własne). Idempotentne są PUT, DELETE i metody bezpieczne, czyli tylko odczytujące — w tym GET. POST idempotentny nie jest.
Dlaczego to ważne? Bo połączenia się zrywają. Standard wyjaśnia, że zapytanie idempotentne można automatycznie ponowić, gdy komunikacja przerwie się, zanim klient odczyta odpowiedź. Dwa razy wysłane „usuń fakturę nr 15” da ten sam wynik co jedno. Dwa razy wysłane „utwórz płatność” może dać dwie płatności. Dlatego integracje płatności wymagają osobnej ochrony przed duplikatami — w naszym kalkulatorze kosztu aplikacji webowej opis tej pozycji mówi wprost, że integracja płatności „wymaga obsługi webhooków, logiki idempotentności i testów compliance — to nie tylko osadzenie widżetu checkout”.
Połączenie zerwane, zapytanie ponowione — co dostaje serwer
Digital Vantage, schemat własny
Starsze systemy — bankowe, administracyjne, korporacyjne — często udostępniają API w innym standardzie: SOAP. Według specyfikacji W3C SOAP 1.2 (rekomendacja z 27 kwietnia 2007 roku) to „a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment” — „lekki protokół przeznaczony do wymiany ustrukturyzowanych informacji w zdecentralizowanym, rozproszonym środowisku” (tłumaczenie własne), oparty na technologiach XML.
Różnica z perspektywy firmy jest praktyczna, nie ideologiczna. SOAP to protokół z własną, ściśle określoną kopertą komunikatu w XML. REST to styl architektury, który korzysta z tego, co HTTP już daje: adresów, metod i kodów odpowiedzi, a dane przesyła zwykle w JSON. Jeśli dostawca udostępnia tylko SOAP, integracja jest jak najbardziej możliwa — wymaga po prostu innych narzędzi i zwykle więcej pracy przy obsłudze komunikatów. Nie podajemy tu statystyk, który standard jest „popularniejszy”, bo nie znaleźliśmy takich, za którymi dałoby się stanąć.
Zwykłe API działa na zasadzie „zapytaj, a dostaniesz odpowiedź”. Jeśli chcesz wiedzieć, czy klient zapłacił, musisz co jakiś czas pytać. Webhook odwraca ten kierunek: to system, u którego coś się wydarzyło, sam wysyła wiadomość na wskazany przez ciebie adres.
GitHub opisuje to w swojej dokumentacji webhooków najprościej, jak się da: webhooki pozwalają „receive data as it happens, as opposed to polling an API (calling an API intermittently) to see if data is available” — „otrzymywać dane w chwili, gdy się pojawiają, zamiast odpytywać API (wywoływać je co jakiś czas), żeby sprawdzić, czy dane są dostępne” (tłumaczenie własne). Stripe, operator płatności, pisze, że po zarejestrowaniu adresu odbiorczego „Stripe pushes real-time data to it when events happen in your Stripe account” — wysyła na niego dane w czasie rzeczywistym, gdy na koncie coś się dzieje, w formacie JSON przez HTTPS.
Zapytanie do API a webhook
Opracowanie własne na podstawie dokumentacji webhooków GitHub i Stripe, odczyt 30.09.2026
W praktyce oba podejścia się uzupełniają. Webhook jest lepszy, gdy liczy się czas reakcji — płatność, nowe zamówienie, zmiana statusu przesyłki. Odpytywanie wystarcza, gdy dane zmieniają się rzadko albo gdy dostawca webhooków po prostu nie oferuje. Stripe daje odbiorcom jedną ważną radę: adres odbierający webhooki powinien szybko zwrócić kod sukcesu (2xx), zanim zacznie wykonywać jakąkolwiek złożoną logikę, która mogłaby spowodować przekroczenie czasu oczekiwania.
Adres, na który przychodzą webhooki, jest publiczny — każdy może wysłać na niego cokolwiek, na przykład fałszywą informację „zamówienie opłacone”. Dlatego poważni dostawcy podpisują każdą wiadomość, a odbiorca musi ten podpis sprawdzić.
Stripe-Signature i generuje go jako HMAC z funkcją SHA-256, używając sekretu przypisanego do danego adresu odbiorczego. Podpisywany jest znacznik czasu razem z treścią wiadomości. Znacznik czasu chroni przed ponownym wysłaniem przechwyconej, starej wiadomości: biblioteki Stripe mają domyślną tolerancję 5 minut między znacznikiem a bieżącym czasem (Stripe, webhooks).X-Hub-Signature-256, zawsze z przedrostkiem sha256=. Dokumentacja ostrzega, żeby nie porównywać podpisów zwykłym operatorem ==, tylko funkcją porównującą „w stałym czasie” — takim porównaniem nie da się odgadywać podpisu po czasie odpowiedzi (GitHub, weryfikacja dostarczeń).HMAC to podpis tworzony wspólnym sekretem: zna go tylko nadawca i odbiorca, więc tylko oni mogą wygenerować i sprawdzić poprawny podpis. Dla właściciela firmy wniosek jest prosty: pytając dostawcę integracji o webhooki, zapytaj też, czy wiadomości są podpisane i czy twój system ten podpis sprawdza.
API bez dokumentacji jest jak umowa, której nikt nie spisał. OpenAPI to standard, w którym tę umowę się zapisuje. Aktualna wersja specyfikacji to OpenAPI Specification 3.2.1, opublikowana 10 września 2026 roku. Jej pierwsze zdanie mówi, czemu służy: „The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic” — „Specyfikacja OpenAPI (OAS) definiuje standardowy, niezależny od języka programowania opis interfejsu dla API działających przez HTTP, który pozwala zarówno ludziom, jak i komputerom poznać i zrozumieć możliwości usługi bez dostępu do kodu źródłowego, dodatkowej dokumentacji czy podglądania ruchu sieciowego” (tłumaczenie własne).
W praktyce plik OpenAPI wymienia wszystkie adresy API, metody, wymagane pola, możliwe odpowiedzi i sposób uwierzytelniania. Z takiego pliku narzędzia same generują czytelną dokumentację w przeglądarce, z której programista może od razu wysłać próbne zapytanie.
Po co to firmie, a nie tylko programistom?
Dlatego w naszym kalkulatorze pozycja „publiczne API / integracje” obejmuje, jak mówi jej opis, „klucze API, rate limiting i dokumentację OpenAPI” — nie tylko sam kod.
API key (klucz API) to długi, losowy ciąg znaków, który identyfikuje program wysyłający zapytania i daje mu dostęp. Najczęściej przekazuje się go w nagłówku Authorization jako tzw. token Bearer — „okaziciela”: kto go ma, ten ma dostęp. Z tego wynikają trzy zasady praktyczne. Klucz trzyma się wyłącznie na serwerze, nigdy w kodzie strony widocznym w przeglądarce ani w wiadomości e-mail. Każda integracja powinna mieć osobny klucz, żeby w razie wycieku dało się unieważnić jeden, a nie wszystkie. Klucze warto okresowo wymieniać.
Część dostawców zamiast stałego klucza stosuje standard OAuth, w którym aplikacja dostaje token w imieniu konkretnego konta — tak jest w API Allegro i InPost opisanych niżej.
Drugi element to limity zapytań (rate limiting). Dostawca ogranicza, ile zapytań można wysłać w danym czasie, żeby jeden klient nie przeciążył usługi. Dobrze zaprojektowane API mówi o tym w odpowiedzi — na przykład nagłówkami z limitem, liczbą pozostałych zapytań i czasem odnowienia. Twoja integracja musi te limity szanować: rozkładać zapytania w czasie i nie ponawiać ich w kółko po odmowie.
Organizacja OWASP, która zajmuje się bezpieczeństwem aplikacji, publikuje osobną listę dziesięciu najważniejszych zagrożeń dla API. Wersja z 2023 roku wygląda tak (tytuły w oryginale, objaśnienia nasze):
Ostatni punkt dotyczy każdej firmy, która tylko korzysta z cudzych API: dane z zewnątrz też trzeba sprawdzać. Jak podzielona jest odpowiedzialność za bezpieczeństwo, gdy dane leżą u zewnętrznego dostawcy, opisujemy w tekście o bezpieczeństwie danych w chmurze.
Większość integracji w polskiej firmie dotyczy kilku tych samych usług. Poniżej zestawienie z odnośnikami do oficjalnej dokumentacji.
API, z których korzysta polska firma
Oficjalna dokumentacja: Ministerstwo Finansów, NBP, GUS, Allegro, InPost, odczyt 30.09.2026
Authorization, jest też środowisko testowe (developer.allegro.pl).Najuczciwszy przykład integracji, jaki możemy pokazać, to nasz własny. DVN Links to nasza polska platforma do skracania linków z analityką i kodami QR. Strona, którą czytasz, korzysta z jej publicznego REST API przy każdej publikacji artykułu lub strony — tego samego API, które dostają klienci planów płatnych (według cennika dostęp do API jest od planu Starter).
Co dokładnie robi nasza strona, w prostych słowach:
POST /links z docelowym adresem i zapisuje w dokumencie krótki adres oraz identyfikator linku.GET /links/{id}, czy link nadal istnieje i dokąd prowadzi.PATCH /links/{id} z nowym adresem docelowym. Stary krótki link dalej działa i prowadzi już pod nowy adres.Dwie decyzje projektowe są tu ważniejsze od samych zapytań. Po pierwsze, integracja nigdy nie blokuje zapisu — jeśli DVN Links nie odpowie, artykuł i tak się opublikuje, a błąd trafi tylko do logów. Po drugie, bez skonfigurowanego klucza API integracja po prostu nic nie robi. Widać tu też w praktyce różnicę z sekcji o idempotentności: POST tworzy nowy zasób, więc przed nim strona zawsze sprawdza, czy link już istnieje.
Co robi nasza strona z API DVN Links przy każdej publikacji
Digital Vantage, schemat własny
Samo API DVN Links ma cechy, o które warto pytać każdego dostawcę. Jest opisane specyfikacją OpenAPI 3.1.0, z której generowana jest dokumentacja w przeglądarce. Wszystkie zapytania wymagają klucza przekazywanego jako token Bearer w nagłówku Authorization. Limity zapytań zależą od planu, a każda odpowiedź niesie nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset.
DVN Links nie ma webhooków. Dlatego to przykład odpytywania: nasza strona sama sprawdza stan linku, kiedy go potrzebuje, zamiast czekać na powiadomienie. Przy tym zastosowaniu to wystarcza, bo link sprawdzamy tylko w chwili publikacji.
Każda integracja przez API zastępuje pracę, którą ktoś w firmie wykonuje ręcznie: przepisuje zamówienia z platformy do systemu magazynowego, kopiuje kurs walut do faktury, sprawdza kontrahenta na białej liście przed przelewem. Pytanie nie brzmi „czy integrować”, tylko „które przepisywanie kosztuje nas najwięcej”.
Integracja przez API zwykle ma sens, gdy:
Integracja nie ma sensu, gdy czynność zdarza się rzadko, a dostawca nie ma API albo zmienia je bez uprzedzenia. Wtedy utrzymanie integracji kosztuje więcej niż ręczna praca.
Koszt samej integracji zależy od jej zakresu. Dla orientacji: w naszym kalkulatorze kosztu aplikacji webowej pozycja „publiczne API / integracje” to +8 000 zł netto, a integracja płatności online +5 000 zł netto — do ceny aplikacji, która zaczyna się od Lean MVP od 10 tys. zł i MVP od 30 tys. zł. To punkt wyjścia, nie cennik: każdą integrację wyceniamy indywidualnie, bo zależy od jakości API po drugiej stronie.
Gdy integracji jest kilka i zaczynają się łączyć w proces — zamówienie, faktura w KSeF, etykieta przesyłki, powiadomienie klienta — to już automatyzacja procesu, a nie pojedyncze połączenie. Piszemy o tym w tekście o automatyzacji procesów biznesowych, a nasze podejście opisuje oferta automatyzacji procesów. Jeśli integracje mają być częścią nowego systemu, zacznij od tekstu o tym, czym jest aplikacja webowa, i od naszej oferty tworzenia aplikacji webowych. Kiedy gotowe narzędzia z integracjami nie wystarczają, zostaje dedykowane oprogramowanie. Pozostałe teksty o aplikacjach webowych zebraliśmy w przewodniku po aplikacjach webowych.
API to ustalony sposób, w jaki jeden program prosi drugi o dane albo o wykonanie czynności, bez udziału człowieka. Przykład: program księgowy sam pobiera kurs euro z serwisu api.nbp.pl, a formularz sam uzupełnia dane kontrahenta z rejestru REGON przez usługę GUS BIR1. API określa, jakie zapytania można wysłać, jakich danych wymagają i co wróci w odpowiedzi.
REST API to API zbudowane według stylu architektury REST, który opisał Roy Fielding w rozprawie doktorskiej z 2000 roku. Każdy zasób, na przykład faktura czy przesyłka, ma swój adres, a operacje wykonuje się standardowymi metodami HTTP: GET pobiera, POST tworzy, PUT zastępuje, DELETE usuwa. Każde zapytanie zawiera wszystkie informacje potrzebne do jego zrozumienia, bo serwer nie przechowuje kontekstu poprzednich zapytań.
Webhook to wiadomość, którą system dostawcy sam wysyła na adres twojego systemu, gdy coś się wydarzy — na przykład gdy płatność zostanie opłacona. Zwykłe API trzeba odpytywać co jakiś czas, a webhook przychodzi w chwili zdarzenia. Adres odbierający webhooki jest publiczny, dlatego dostawcy tacy jak Stripe czy GitHub podpisują wiadomości kodem HMAC SHA-256, a odbiorca powinien ten podpis sprawdzać.
Klucz API to długi, losowy ciąg znaków, który identyfikuje program wysyłający zapytania i daje mu dostęp do API. Zwykle przekazuje się go w nagłówku Authorization jako token Bearer, więc kto ma klucz, ten ma dostęp. Klucz trzyma się wyłącznie na serwerze, każda integracja powinna mieć osobny klucz, a klucze warto okresowo wymieniać.
Może być, jeśli spełnia kilka warunków: klucze są przechowywane tylko na serwerze, API sprawdza uprawnienia do każdego rekordu i ma limity zapytań, webhooki są podpisane i weryfikowane, a dane z cudzych API są sprawdzane przed użyciem. Listę najczęstszych błędów zawiera OWASP API Security Top 10 2023 — to dobry punkt wyjścia do rozmowy z wykonawcą integracji.
Sprawdzimy, które dane Twoja firma dziś przepisuje ręcznie, jakie API udostępniają Twoi dostawcy i czy integracja się opłaci.
Poradniki o budowie aplikacji dla firm: czym jest aplikacja webowa, jak przebiega projekt, ile kosztuje, jak zaplanować MVP, PWA i aplikacja mobilna.
Co to jest MVP (minimum viable product), czym różni się od proof of concept i prototypu, jak wyciąć zakres metodą MoSCoW i jaką miarą sprawdzić wynik.
Co to jest PWA, jak działa service worker i instalacja na Androidzie i iPhonie, powiadomienia push od iOS 16.4 i czego PWA nie zrobi. Z macierzą możliwości.
Ile kosztuje stworzenie aplikacji: dlaczego nie ma publicznego cennika, jak wyliczyć stawkę i zakres, mediany z naszego raportu i koszty po starcie.
Jak stworzyć aplikację dla firmy z wykonawcą: brief, prototyp, programowanie, testy UAT i wdrożenie. Ile to trwa i w których trzech momentach decydujecie Wy.
Jak stworzyć aplikację na telefon dla firmy: Android czy iOS, natywna czy wieloplatformowa, konto z numerem DUNS, test zamknięty i przegląd wersji.
Aplikacja webowa to nie rozbudowana strona. Czym się różnią, jakie są rodzaje aplikacji webowych, ile kosztują i kiedy naprawdę warto je budować.
Twoj Partner w Biznesie, zespół Digital Vantage
Zespół Digital Vantage to grupa doświadczonych specjalistów łączących kompetencje z zakresu web developmentu, inżynierii oprogramowania, DevOps, UX/UI designu oraz marketingu cyfrowego. Wspólnie realizujemy projekty od koncepcji po wdrożenie — strony internetowe, sklepy e-commerce, dedykowane aplikacje i strategie digitalowe. Nasz zespół łączy wieloletnie doświadczenie z korporacji technologicznych z elastycznością i bezpośredniością, jaką daje praca w mniejszej, zgranej strukturze. Pracujemy w metodykach zwinnych, stawiamy na przejrzystą komunikację i traktujemy każdy projekt jak własny biznes. Siłą zespołu jest różnorodność perspektyw — od architektury systemów i infrastruktury, przez frontend i design, po SEO i strategię content marketingową. Dzięki temu klient otrzymuje spójne rozwiązanie, w którym technologia, estetyka i cele biznesowe idą w parze.
Spis treści · 8 sekcji · 17 minut czytania
Oceń artykuł
Wróć do przewodnika: Aplikacje webowe i mobilne dla firm — przewodnik po budowie, decyzja po decyzji

Omnichannel w e-commerce: definicja, różnica wobec multichannel, wspólny stan magazynowy sklepu i kasy oraz dane Gemius o popularności click & collect w Polsce.

Fulfillment w e-commerce: co obejmuje, ile kosztuje One Fulfillment by Allegro, kto wycenia indywidualnie (InPost, Omnipack) i kiedy to się opłaca.

Multi-tenant, czyli wielu klientów w jednej aplikacji: single tenant a multi-tenant, modele silo/pool/bridge, Row Level Security, RODO i wybór modelu dla MVP.

Chmura obliczeniowa według definicji NIST: pięć cech, IaaS, PaaS i SaaS, chmura publiczna, prywatna i hybrydowa oraz dane o firmach w Polsce i UE.

Kiedy wystarczy darmowy kalendarz rezerwacji, co musi umieć system rezerwacji online i kiedy własny moduł się zwraca. Ceny narzędzi i nasza wycena.

Jak działa krótki link, gdzie ma sens (SMS, e-mail, bio, druk), jak tagować go UTM, żeby nie zniknął w GA4, i po czym wybrać skracacz.

Cztery typy stron opisane przez zadanie, nie przez liczbę podstron. Trzy pytania, które rozstrzygają wybór, i jedna rzecz, której nie da się dołożyć później.

91% podatności WordPressa siedzi we wtyczkach, w rdzeniu znaleziono sześć. A 46% luk nie ma poprawki w dniu ujawnienia — co zmienia sens rutyny.

Włamania to 0,3% incydentów w Polsce, phishing po hasła — 30% (CERT 2025). Dlatego zabezpieczenie strony to głównie kontrola dostępu, nie wtyczki i firewall.