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 Słowniki (document-type, vat-rate, party-kind, inventory-document-movement-type itd.) z wariantami domenowymi, identyfikatory (https://gov.pl/nip, https://gov.pl/regon, przestrzenie OID instalacji), powiązanie z modelami.
Kontrakty API Lista zasobów i wszystkich tras /v1/... (ścieżka, metody, obszar, parametry); link do Portalu dla Integratorów (APIM), przez który API jest publikowane.
Profile kanoniczne Schematy JSON *.schema.json (m.in. Party z profilami Employee/Employer/Contractor/AssetHolder, Location, DocumentReference, FixedAsset, PostingInstruction, PurchaseOrder, Invoice) — kardynalności, opisy pól i powiązania ze słownikami; generowane z modelu kanonicznego (nie edytuj ręcznie — użyj zestawu z tej samej wersji przewodnika / API).
Identyfikacja i parametry wdrożenia Co jest stałe (IG), a co jest parametrem instalacji: karta GET /v1/metadata, profile, przestrzenie identyfikatorów (GET /v1/naming-systems), słowniki wdrożeniowe.

Źródłem kontraktu jest ten przewodnik wraz z Portalem dla Integratorów (APIM). W openapi/ są wyłącznie kontrakty odbiorcy dla trybów wychodzących: API-ERP-Notification-Receiver.yaml i API-ERP-Report-Receiver.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, DocumentReference, 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 obszarami księgowości, magazynu, majątku i kadr.

→ 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.

→ Specyfikacja

2. 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.

Tryb rozgłoszeniowy działa naprzemiennie z trybem notyfikacyjnym, co oznacza, że może być aktywny tylko jeden z nich.

→ Specyfikacja

3. 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.

Tryb notyfikacyjny działa naprzemiennie z trybem rozgłoszeniowym, co oznacza, że może być aktywny tylko jeden z nich.

→ Specyfikacja

4. 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.

→ Specyfikacja · Specyfikacja szczegółowa

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 (księgowość, magazyn, majątek, kadry) — Kontrakty API.

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