API.ERP — Wprowadzenie
API.ERP udostępnia dane i procesy systemów klasy ERP (księgowość, magazyn, kadry, majątek) w czterech trybach, w zależności od charakteru integracji.
| Tryb | Kiedy używać | Charakter | Dokumentacja |
|---|---|---|---|
| Żądaniowy (REST) | Integrator potrzebuje konkretnych danych na żądanie (np. pobranie/zmiana pojedynczego zasobu) | Synchroniczny, request/response | Tryb żądaniowy |
| Rozgłoszeniowy | Integrator chce dostawać pełną zawartość zasobu natychmiast po zmianie, bez odpytywania | Asynchroniczny, push pełnego zasobu, sterowany zdarzeniami w systemach dziedzinowych | Tryb rozgłoszeniowy |
| Notyfikacyjny | Integrator chce tylko wiedzieć o zmianie (bez treści), a pełne dane pobiera na żądanie | Asynchroniczny, push samego powiadomienia (awizo) — lżejszy wariant trybu rozgłoszeniowego | Tryb notyfikacyjny |
| Raportowy | Integrator potrzebuje dużych wolumenów danych analitycznych, poza modelem transakcyjnym | Asynchroniczny, zlecenie → wynik w repozytorium integratora | Tryb raportowy |
Rozgłoszeniowy i Notyfikacyjny działają naprzemiennie — dla danego zasobu obowiązuje zawsze tylko jeden z nich, ustalony w ramach integracji.
Wszystkie tryby współdzielą ten sam model kanoniczny (zasoby, CodeableConcept, Reference, Identifier) opisany w Zasoby i Systemy kodowania — różni je wyłącznie sposób dostarczenia danych integratorowi, nie kształt samych danych.
Wspólny wzorzec: trzy role
We wszystkich trybach powtarza się ten sam układ ról:
- Aplikacja integratora — konsument API, po stronie zewnętrznego systemu.
- API.ERP — warstwa pośrednicząca, tłumacząca model kanoniczny na wywołania do systemów dziedzinowych i odwrotnie.
- Systemy dziedzinowe (księgowość, magazyn, kadry, majątek) — źródła prawdy dla danych biznesowych.
Tryby różnią się tym, kto inicjuje przepływ (integrator w trybie żądaniowym i raportowym, system dziedzinowy w trybie rozgłoszeniowym i notyfikacyjnym) i gdzie ląduje wynik (bezpośrednio w odpowiedzi, w repozytorium zasobów, w repozytorium raportów integratora).
Cel dostarczenia (storage.type)
Tryby wychodzące — rozgłoszeniowy, notyfikacyjny i raportowy — dostarczają wynik do magazynu docelowego integratora, opisanego jednym wspólnym modelem: obiekt storage, w którym pole storage.type wybiera rodzaj celu, a towarzyszące mu pole połączenia zależy od typu. Niezależnie od trybu i typu dane lądują po stronie integratora — nie w infrastrukturze KAMSOFT (KAMSOFT nie przechowuje kopii). Ładunek jest szyfrowany/serializowany zgodnie z danym trybem przed dostarczeniem.
storage.type |
Rodzaj celu | Pole połączenia (zależne od typu) | Aliasy (akceptowane wstecznie) |
|---|---|---|---|
blob |
Azure Blob Storage (kontener) | connectionString (np. BlobEndpoint=...;SharedAccessSignature=...) |
AzureBlob, BlobStorage |
http |
Endpoint HTTP integratora (POST) | adres URL; uwierzytelnianie zależne od trybu (patrz nota niżej) | HttpEndpoint, HttpPost |
local |
Katalog w systemie plików | ścieżka katalogu | Directory, FileSystem |
smb |
Udział sieciowy SMB | ścieżka udziału + poświadczenia | — |
Wartości type są nieczułe na wielkość liter; aliasy (starsze/rozwlekłe nazwy z eksportu i wcześniejszych wersji IG) są mapowane wstecznie na wartości kanoniczne — patrz komentarze w kodzie fabryk celu.
Uprawnienia (cel typu magazyn — blob, local, smb): API.ERP wyłącznie zapisuje i tworzy obiekty (oraz tworzy kontener/katalog, jeśli nie istnieje) — nie odczytuje, nie usuwa, nie listuje. Dla SAS: uprawnienia Write + Create w zakresie kontenera i obiektów; zalecany SAS ograniczony do jednego kontenera, z terminem ważności.
Uwierzytelnianie celu http a moment dostarczenia: model uwierzytelniania różni się między trybami i wynika z momentu wysyłki:
- Push (rozgłoszeniowy, notyfikacyjny) — API.ERP generuje uwierzytelnienie w chwili wysyłki (np. świeży JWT z konfiguracji integracji lub Basic), więc jest zawsze aktualne.
- Raportowy — dostarczenie następuje wg
runAt(nawet za kilka dni), a API.ERP przekazuje jedynie statyczny nagłówekAuthorizationzstorage.connectionStringi nie odświeża tokenów. Dlatego token krótkotrwały (Bearer/JWT) się nie nadaje — użyj poświadczenia ważnego w chwili dostarczenia (długoterminowy klucz/API key) albo endpointu bez tokenu czasowego.
Który tryb wspiera który typ i jak wskazuje cel:
| Tryb | Obsługiwane storage.type |
Kiedy wskazywany | Co trafia do celu |
|---|---|---|---|
| Rozgłoszeniowy | blob, http, local |
per subskrypcja (w ramach integracji) | pełny zasób kanoniczny; dla usunięcia — metadane elementu kolejki |
| Notyfikacyjny | blob, http, local |
per subskrypcja (w ramach integracji) | Notification (awizo) |
| Raportowy | blob, http, local, smb |
per żądanie — pole storage w POST /v1/reports |
zaszyfrowany artefakt raportu |
Dostarczanie, ponawianie, idempotencja (wspólne dla trybów wychodzących): dostarczenie jest uznane po udanym zapisie obiektu (cel typu magazyn) lub odpowiedzi 2xx (cel http). Niepowodzenie (brak 2xx / brak połączenia / timeout / błąd zapisu) skutkuje ponowieniem wg polityki retry; po wyczerpaniu prób element trafia do martwej kolejki (dead-letter) i wymaga interwencji lub ponownego zlecenia. Ponawianie oznacza możliwe duplikaty — odbiorca musi być idempotentny (rozróżnianie po id/reference, a w trybie raportowym po ks-report-execution-id). Kolejność dostarczenia nie jest gwarantowana.