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 zgodny z modelem w kodzie). 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 (urn:pl:nip, urn: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; zgodne z modelem w kodzie (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
Dokumentacja dodatkowa
Poniższe strony nie mają osobnej pozycji w menu nawigacji; linki prowadzą bezpośrednio do plików:
- Konwencje techniczne — base URL, auth, nagłówki, paginacja, błędy, wersjonowanie
- Bezpieczeństwo — transport, tokeny, scopes, audyt
- Kontrakty API — zasoby i endpointy per obszar (22 domeny)
- Scenariusze — szablony procesów (kroki, wywołania API)
- Przykłady — wprowadzenie — uzupełnienie do przykładów przy modelach w menu Standard Kamsoft.FAIR → Przykłady
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. Implementacje częściowo zgodne należy jawnie opisać.
Wersjonowanie i zmiany
| Wersja | Data | Opis |
|---|---|---|
| 0.1 | (do uzupełnienia) | Szkielet guide — standard FAIR, API kanoniczne (APIM), systemy kodów; dokumentacja dodatkowa poza menu |
Spis treści (linki)
Istotne:
- Standard Kamsoft.FAIR
- Systemy kodów i value sety
- API kanoniczne — przegląd — APIM, taksonomia, OpenAPI YAML
- Profile kanoniczne — snapshot JSON profilu zasobów
Dodatkowo (poza menu): Konwencje techniczne · Bezpieczeństwo · Kontrakty API · Scenariusze · Przykłady — wprowadzenie