Kontrakty API
Źródło prawdy dla integratora jest opublikowana specyfikacja OpenAPI w Portalu dla Integratorów (APIM) oraz pliki YAML w repozytorium (docs/openapi/). Niniejszy dokument mapuje obszary funkcjonalne (taksonomię domen) na API kanoniczne udostępnione w ramach API.ERP oraz wskazuje konwencje wspólne dla wywołań.
Mapa domen: domain-taxonomy.md — 22 domeny pogrupowane w 9 grup.
DomainResource: Zasoby biznesowe dziedziczą z DomainResource (wzorowanie na FHIR). Opis: Resources/DomainResource.md.
Konwencje wywołań: technical-conventions.md — m.in. wersja w ścieżce /v1/, kebab-case w URI kolekcji, snake_case w parametrach zapytania, camelCase w JSON, PATCH z samymi zmienianymi polami, błędy RFC 7807.
Identyfikacja i kody: technical-conventions.md — §12 (Identifier, Coding, CodeableConcept). Wymagalność pól i dopuszczalne wartości system / use wynikają z OpenAPI dla zasobu i profilu.
Wyszukiwanie po identyfikatorze biznesowym: technical-conventions.md — §12.4.
Przegląd ścieżek i zasobów EOD / WMS / HR: canonical/README.md.
Status publikacji API kanonicznych
| Grupa domen | Zakres w API kanonicznym | Specyfikacja |
|---|---|---|
| A. Finance Core | BankAccount, Invoice, PostingInstruction, JournalEntry, JournalEntryPosition, Document, Ledger, LedgerEntry, Register, AccountingVariant, CostCarrier, CostAssignment | API-ERP-Canonical-EOD.yaml |
| E. Procurement-to-Pay (część WMS) | InventoryDocument, Inventory, Location, Product, ProductDefinition | API-ERP-Canonical-WMS.yaml |
| E. Human Capital | OrganizationUnit, Party, PartyRole, Employment, Position, Capability, GrantAssignment | API-ERP-Canonical-HR.yaml |
| Pozostałe grupy (C, D, F, G, I itd.) | Brak w powyższych plikach OpenAPI — nie są częścią kontraktu API kanonicznego opisanego w tym Implementation Guide, o ile operatorem API nie udostępniono osobnej specyfikacji dla danego projektu integracji. | Zgodnie z umową i APIM |
0. API kanoniczne — EOD/FK, WMS, HR
Źródło: OpenAPI 3.0: API-ERP-Canonical-EOD.yaml, API-ERP-Canonical-WMS.yaml, API-ERP-Canonical-HR.yaml (katalog docs/openapi/ w repozytorium oraz publikacja w APIM).
Zakres:
- EOD / FK (
/v1/...): m.in. Party, BankAccount, Document (bez dekretacji faktury), Invoice (lines[]— InvoicePosition), PostingInstruction (/v1/posting-instructions— bufor dekretacji), JournalEntry / JournalEntryPosition (wynik dekretacji), Register, AccountingVariant, CostCarrier, CostAssignment, Ledger / LedgerEntry. Nagłówki i parametry — zgodnie z OpenAPI (np.ks-system-identification, parametrcompany). - WMS (
/v1/...): m.in. Party, Location, ProductDefinition, Inventory, Document dla ruchów magazynowych i zapotrzebowań. Te same zasady nagłówków i parametrów co w specyfikacji.
Konwencje: Paginacja i błędy — jak w OpenAPI (np. _count / _offset, ProblemDetails). Modele: Identifier, CodeableConcept, Reference.
1.–7. Pozostałe obszary taksonomii (Finance szerszy, sprzedaż, produkcja, jakość, master data, pole field service itd.)
Powiązanie numerów domen i grup z modelem danych i endpointami poza trzema plikami OpenAPI kanonicznych nie jest częścią tego Implementation Guide. Integracja w tych obszarach opiera się na osobnych kontraktach udostępnionych przez operatora API (APIM, dokumentacja projektowa).
Dla mapowania pojęć biznesowych na przyszłe zasoby służy wyłącznie domain-taxonomy.md jako klasyfikacja, bez implikacji co do dostępności endpointów.