REST API
REST API to interfejs, przez który jeden system udostępnia innym swoje dane i funkcje w formie zasobów dostępnych pod adresami URL, obsługiwanych standardowymi metodami HTTP: GET, POST, PUT, PATCH i DELETE. Odpowiedzi najczęściej mają format JSON. W obiegu dokumentów REST API łączy system workflow z ERP, systemem finansowo-księgowym, KSeF czy portalem klienta bez ręcznego przenoszenia danych.
Jak działa REST API: zasoby, metody, odpowiedzi
W REST każdy obiekt biznesowy jest zasobem z własnym adresem, na przykład faktura numer 123 pod adresem /api/faktury/123. Metoda HTTP mówi, co chcemy zrobić: GET pobiera dane, POST tworzy nowy obiekt, PUT lub PATCH zmienia istniejący, DELETE usuwa. Serwer odpowiada kodem stanu - 200 gdy wszystko poszło dobrze, 201 gdy coś utworzono, 400 gdy żądanie jest błędne, 401 gdy klient się nie uwierzytelnił, 403 gdy nie ma uprawnień, 404 gdy zasobu nie ma - oraz treścią, zwykle w formacie JSON, czyli czytelnym tekstowym zapisie pól i wartości. Każde żądanie jest samowystarczalne, serwer nie pamięta poprzednich, co ułatwia skalowanie i testowanie. Dobre API ma dokumentację w standardzie OpenAPI, z której widać wszystkie zasoby, pola i przykładowe odpowiedzi.
Uwierzytelnianie i bezpieczeństwo REST API
Dostęp do API zabezpiecza się kluczem API, tokenem uzyskiwanym przez OAuth 2.0 albo certyfikatem - KSeF na przykład wymaga uwierzytelnienia przed pobraniem faktur. Cała komunikacja idzie przez HTTPS, a uprawnienia nadaje się osobno dla każdego zasobu i operacji: system HR może odczytać listę pracowników, ale nie zmienić dekretu faktury. Dostawcy API zwykle ograniczają liczbę wywołań w jednostce czasu i logują każde żądanie, dzięki czemu przy audycie widać, kto i kiedy pobrał dane. Po stronie firmy kluczowe jest przechowywanie kluczy poza kodem i regularna ich rotacja.
REST API a inne sposoby integracji
- SOAP - starszy protokół oparty na XML, nadal spotykany w systemach ERP i bankowych, bardziej rozwlekły, ale z formalnym opisem usług.
- Wymiana plików - CSV lub XML wrzucane na serwer SFTP i przetwarzane wsadowo, na przykład raz na godzinę. Proste, ale bez natychmiastowej reakcji i kontroli błędów.
- Webhook - odwrotny kierunek: to system źródłowy sam wysyła powiadomienie, gdy coś się zdarzy, zamiast czekać, aż ktoś zapyta.
- Integracja bazodanowa - odczyt widoków wprost z bazy drugiego systemu, szybki, lecz łamiący się przy każdej aktualizacji.
REST jest dziś najpopularniejszym sposobem budowy API: korzystają z niego nowoczesne systemy ERP, platformy e-commerce, banki, e-Doręczenia i API KSeF.
REST API w obiegu dokumentów: co się integruje
W elektronicznym obiegu dokumentów integracje przez API załatwiają to, co dawniej przepisywano ręcznie: pobranie kontrahentów, kont i miejsc powstawania kosztów z systemu finansowo-księgowego, wysłanie zaakceptowanej faktury do zaksięgowania, pobranie faktur z KSeF, synchronizację pracowników i struktury organizacyjnej z systemu kadrowego, przekazanie paczki przelewów do banku, odbiór zgłoszeń z portalu klienta.
Platforma JobRouter, na której e-MSI buduje procesy, łączy się z innymi systemami przez API i webserwisy, synchronizację baz danych, wymianę plików i gotowe łączniki. W projektach e-MSI była integrowana m.in. z systemami ERP (SAP, Microsoft Dynamics, Symfonia, enova365), z KSeF, e-Doręczeniami i Active Directory. Opracowany przez e-MSI system IDR przekazuje dane odczytane z dokumentów przez REST API lub w plikach CSV, JSON i XML. Dzięki temu proces obiegu faktury zaczyna się i kończy w systemach, które firma już ma, a workflow jest warstwą pośrednią, nie kolejną wyspą danych. Więcej na stronie integracja JobRouter.
Na co uważać przy integracji przez REST API
- Brak lub nieaktualna dokumentacja API po stronie dostawcy ERP - sprawdź to przed podpisaniem umowy wdrożeniowej.
- Zmiany wersji API bez zapowiedzi, które z dnia na dzień psują integrację.
- Limity wywołań, przez które masowa synchronizacja w nocy musi być podzielona na partie.
- Obsługa błędów i ponowień: żądanie wysłane dwa razy nie może utworzyć dwóch faktur.
- Mapowanie słowników - kontrahent, MPK czy konto muszą oznaczać to samo w obu systemach.
- Środowisko testowe u obu stron i monitoring integracji po uruchomieniu.
Przykłady zastosowania
Po ostatniej akceptacji faktury system workflow wysyła metodą POST komplet danych i dekret do systemu finansowo-księgowego, a w odpowiedzi dostaje numer dokumentu księgowego.
Przy rejestracji faktury proces wysyła metodą GET zapytanie do API systemu ERP z NIP sprzedawcy i w odpowiedzi dostaje kartotekę kontrahenta z domyślnym kontem i MPK, które podpowiada w formularzu.
Klient składa reklamację w portalu internetowym. Portal wywołuje API systemu obiegu dokumentów, które tworzy nową instancję procesu reklamacyjnego i zwraca numer zgłoszenia.
Każdej nocy proces pobiera przez API systemu kadrowego listę pracowników i zmiany stanowisk, dzięki czemu e-teczka i ścieżki akceptacji wniosków są zawsze aktualne.
Zaakceptowane faktury z terminem płatności na jutro trafiają jako paczka przelewów do banku przez jego API, bez ręcznego wpisywania kwot w bankowości.
Najczęstsze pytania
Czym się różni API od REST API?
API to każdy interfejs, przez który programy komunikują się ze sobą. REST API to jego najpopularniejsza odmiana w internecie: dane są zasobami pod adresami URL, operacje wykonuje się metodami HTTP, a odpowiedzi przychodzą zwykle w formacie JSON. Większość nowoczesnych systemów udostępnia właśnie REST API.
Na czym polega REST API?
REST API polega na tym, że system udostępnia dane jako zasoby pod adresami URL, na przykład /faktury/123. Inny program wysyła na ten adres żądanie HTTP z metodą GET, POST, PUT, PATCH lub DELETE, a serwer odsyła kod statusu i odpowiedź, zwykle w formacie JSON. Każde żądanie zawiera komplet potrzebnych informacji, bo serwer nie przechowuje stanu sesji klienta.
Czym różni się REST od SOAP?
SOAP to starszy protokół oparty na XML, z formalnym opisem usług i większym narzutem. REST to styl architektury, a nie protokół - jest prostszy, lżejszy i używa zwykłych metod HTTP oraz JSON. W praktyce oba spotyka się w integracjach z ERP - wybór zależy od tego, co udostępnia dany system, a nie od preferencji wdrożeniowca.
Czy REST API jest bezpieczne?
Tak, jeśli jest poprawnie zabezpieczone: HTTPS, uwierzytelnianie tokenem lub certyfikatem, uprawnienia ograniczone do potrzebnych zasobów, limity wywołań i logowanie. Ryzyko powstaje, gdy klucze API trafiają do kodu lub maili albo gdy jedno konto techniczne ma pełne uprawnienia do wszystkiego.
Czy integracja przez REST API wymaga programowania?
Zwykle wymaga konfiguracji i mapowania pól, a kod pisze się tylko dla nietypowych przypadków. Platformy workflow mają gotowe łączniki do popularnych systemów i możliwość wywołania dowolnego API z kroku procesu, więc dużą część integracji przygotowuje się bez programowania.
Co zrobić, gdy nasz system ERP nie ma REST API?
Sprawdzić, czy ma SOAP, eksport plikowy albo dostęp do bazy danych - każdy z tych kanałów da się obsłużyć, choć z mniejszą wygodą. Alternatywą jest warstwa pośrednia (middleware lub iPaaS), która udostępnia REST API na zewnątrz, a wewnątrz rozmawia ze starszym systemem po swojemu.
Powiązane hasła
Zobacz, jak wygląda to w systemach, które wdrażamy w polskich firmach.
