Przejdź do treści

API.ERP Implementation Guide — przewodnik implementacji API

Implementation Guide dla naszego systemu ERP — definiuje przestrzeń do analizy i dostarcza standard modeli (Kamsoft.FAIR), API kanoniczne (system księgowy i obieg dokumentów, WMS, HR), systemy kodów oraz profile kanoniczne (snapshot JSON spójny z modelem kanonicznym w tym repozytorium). Główni odbiorcy: integratorzy (kontrakty, przykłady, ograniczenia pól), a także analitycy, zespoły dev/architektura i partnerzy. Układ stron jest zbliżony do klasycznego przewodnika implementacji: wprowadzenie, nawigacja po zasobach, przykłady i artefakty do pobrania.

Co jest w tym przewodniku (najważniejsze)

Element Opis
Standard Kamsoft.FAIR Wszystkie modele kanoniczne należą do standardu Kamsoft.FAIR (Fast Adaptive Interoperable Resources) — zestaw zasobów pod szybką adaptację i interoperacyjność.
Systemy kodów i value sety Code systemy (document-type, vat-rate, party-role, inventory-movement-type itd.), value sety, identyfikatory (https://gov.pl/nip, https://gov.pl/regon), powiązanie z modelami.
API kanoniczne Link do Portalu dla Integratorów (APIM) z pełnym API; przegląd domen, pliki OpenAPI YAML (docs/openapi/), ścieżki /v1/....
Profile kanoniczne Pliki *.profile.json (m.in. AccountingVariant, CostAssignment, FixedAsset, ProfessionalGroup, Register, PurchaseOrder, Invoice) — kardynalności, opisy pól i powiązania z ValueSet; spójne z artefaktami OpenAPI / JSON Schema w tym repozytorium (nie edytuj ręcznie — użyj zestawu z tej samej wersji przewodnika / API).

Szczegóły endpointów i wywołań: Portal dla Integratorów (APIM). Pliki OpenAPI w repozytorium: docs/openapi — API-ERP-Canonical-EOD.yaml, API-ERP-Canonical-WMS.yaml, API-ERP-Canonical-HR.yaml.

Standard modeli Kamsoft.FAIR

W tym przewodniku wszystkie modele kanoniczne należą do standardu Kamsoft.FAIR (Fast Adaptive Interoperable Resources).

Kamsoft.FAIR to marka i zestaw zasobów zaprojektowanych pod szybką adaptację i interoperacyjność: Party, Document, Location, InventoryDocument, Employment i pozostałe zasoby z menu Standard Kamsoft.FAIR są zdefiniowane w tym samym stylu (Identifier, CodeableConcept, Reference, DomainResource). Jednolity standard ułatwia integrację między systemami ERP, WMS, HR i FK.

→ Standard modeli Kamsoft.FAIR

Tryby API.ERP

1. Tryb Żądaniowy

Klasyczny model synchroniczny typu klient-serwer. Odbiorca wysyła zapytanie HTTP (Request) do punktu końcowego (Endpoint) i oczekuje w tym samym połączeniu na natychmiastową odpowiedź (Response) zawierającą wnioskowane dane.

2. Tryb Raportowy

Model asynchroniczny sterowany czasem. Zlecenie przetwarzania danych jest rejestrowane przez API, a jego faktyczna realizacja odbywa się zgodnie z zaplanowanym harmonogramem. Gotowy wynik końcowy w postaci raportu jest automatycznie deponowany w dedykowanym dla klienta repozytorium.

→ Zakładka raporty

3. Tryb Rozgłoszeniowy

Automatyczna synchronizacja oparta na wewnętrznych zdarzeniach systemu (Event-Driven). W momencie zajścia określonego zdarzenia, API samodzielnie generuje, mapuje i tworzy realne zasoby, a następnie natychmiast eksportuje ich pełną zawartość do wskazanego repozytorium zasobów odbiorcy.

4. Tryb Notyfikacyjny

Lekki model asynchroniczny z odroczonym pobieraniem danych. API emituje jedynie krótkie powiadomienie (awizo) zawierające referencję (identyfikator/URL) do nowo powstałego zasobu, nie przesyłając jego zawartości. Strona odbiorcza decyduje, kiedy i czy w ogóle pobrać pełny zasób za pomocą standardowego zapytania API.

Dokumenty pionowe (verticals)

Oś pionowa uzupełnia domeny: konkretne profile dokumentów (np. e-skierowanie MP). Placeholdery w api-contracts.md §1–7 pozostają bez zmian.

Zasób Opis
verticals/README.md Rejestr dokumentów pionowych, reguły pakietu
verticals-index.md Indeks skrócony (most poziomy ↔ pionowy)
API-ERP-MP-dokumentacja.md E-skierowanie medycyny pracy (CDA v0.3, draft)

API kanoniczne EOD/FK/WMS — api-contracts.md §0, canonical/README.md.

Dokumentacja dodatkowa

Poniższe strony nie mają osobnej pozycji w menu nawigacji (poza Dokumenty pionowe); linki prowadzą bezpośrednio do plików:

Conformance (zgodność z guide)

Conformance odnosi się do wypracowanego standardu (po doprecyzowaniu). Implementacja zgodna z IG powinna: korzystać z API i operacji z Kontraktów API, stosować Konwencje techniczne, spełniać Bezpieczeństwo, realizować Scenariusze zgodnie z krokami; dla dokumentów pionowych — zgodność z pakietem w verticals/ (patrz rejestr). Implementacje częściowo zgodne należy jawnie opisać.

Spis treści (linki)

Istotne:

Dokumenty pionowe: verticals/ · E-skierowanie MP

Dodatkowo (poza menu): Konwencje techniczne · Bezpieczeństwo · Kontrakty API · Scenariusze · Przykłady — wprowadzenie