Kontrakty API
Źródłem kontraktu dla integratora jest ten przewodnik (model zasobów, profile, słowniki, konwencje wywołań, trasy poniżej) wraz z Portalem dla Integratorów (APIM), przez który API jest publikowane i zabezpieczane. Zakres faktycznie dostępny w danej instalacji opisuje karta wdrożenia GET /v1/metadata (Identyfikacja i parametry wdrożenia).
DomainResource: Zasoby biznesowe dziedziczą z DomainResource (wzorowanie na FHIR). Opis: Resources/DomainResource.md.
Konwencje wywołań: technical-conventions.md — wersja w ścieżce /v1/, kebab-case w URI kolekcji, camelCase w parametrach zapytania i w JSON, paginacja count/offset, koperta { "items": [...], "nextToken": null }, błędy Problem Details (RFC 9457).
Identyfikacja i kody: technical-conventions.md — §12 (Identifier, Coding, CodeableConcept). Wymagalność pól i dopuszczalne wartości wynikają ze schematu profilu zasobu i ze słowników.
Wyszukiwanie po identyfikatorze biznesowym: technical-conventions.md — §12.4.
Zasoby w API
Lista zasobów odpowiada rejestrowi zasobów API.ERP; każdy ma wpis w karcie wdrożenia (rest[].resource[]).
| Obszar | Zasoby |
|---|---|
| Wspólne | CapabilityStatement (karta), NamingSystem, ValueSet, CodeableConcept, Attachment, Party (profile Employee, Employer, Contractor, AssetHolder), PartyRole, PartyRelationship, Location (profile Warehouse, StorageLocation, UsagePlace), DocumentReference (profile HrInboxDocument, WarehouseDocument) |
| Księgowość | PostingInstruction, JournalEntry, Payment, Register, AccountingVariant, CostCarrier, CostAssignment, FormulaComponent; raporty CostCalculationReport, ProductLevelCostCalculationReport (tryb raportowy) |
| Majątek | FixedAsset, AssetComponent, FixedAssetDocument, FixedAssetAllocation, CostCenter |
| Kadry | Employment, Position, OrganizationUnit, OrganizationAssignment, Qualification, ProfessionalGroup, EmployeeProfessionalGroup, Capability, GrantAssignment |
| Magazyn | ProductDefinition, Inventory, InventoryDocument, ReturnDocument, PurchaseOrder, PurchaseRequisition, Invoice |
BankAccount nie ma własnego endpointu — występuje wyłącznie jako zasób zagnieżdżony w contained strony (Party, BankAccount). Typy Document, Ledger, LedgerAccount, LedgerEntry, Group, Compensation, Payroll, Bundle i Product nie są zasobami tego API.
Trasy
Wszystkie trasy wymagają roli API.<Zasób>.Read (GET) albo API.<Zasób>.Write (POST, PATCH) — Bezpieczeństwo. Odczyt kolekcji przyjmuje count (domyślnie 20) i offset; parametry filtrujące per zasób wymienia karta wdrożenia w rest[].resource[].searchParam[] (obiekty { "name", "type" }), operacje $… i raporty — w operation[] z adresem definicji (karta wdrożenia). Brak tras z {id}: zasób wskazuje się parametrem identifier=system|value.
Parametry z karty są obsługiwane, a podany filtr jest stosowany albo odrzucany statusem 400: wartość kodowana (system|value) jest rozpoznawana po każdym słowniku zadeklarowanym dla zasobu, a przestrzeń spoza tych słowników kończy się 400 z nazwą parametru — nigdy pełną, niefiltrowaną listą (konwencje techniczne §8.1). Instalację obsługującą żądanie wyznacza profil zasobu, a gdy podano przestrzeń identyfikatora — ta przestrzeń; przestrzeń wskazująca instalację, która profilu nie obsługuje, kończy się 404 (§6.1). W odczycie kolekcji daje to trzy tory: z parametrem profile odpowiada tylko pierwszy w kolejności system honorujący ten profil, z parametrem identifier — wyłącznie instalacja wskazana przestrzenią, a bez obu zawężeń odpowiedź jest złączeniem wyników wszystkich instalacji rozumiejących ten zasób (tory odczytu).
| Ścieżka | Metody | Obszar | Zasób |
|---|---|---|---|
/v1/metadata |
GET | wspólne | CapabilityStatement |
/v1/naming-systems |
GET | wspólne | NamingSystem (usage) |
/v1/value-sets |
GET | wspólne | ValueSet (url, system, id, owner, status, attribute) |
/v1/codeable-concepts |
GET | wspólne (majątek) | CodeableConcept (system, coding, owner) |
/v1/attachments |
GET, POST | wspólne | Attachment (attribute) |
/v1/parties |
GET, POST, PATCH | wspólne | Party (profile, type, identifier, owner, attribute, status, lastModified) |
/v1/party-roles |
GET | kadry | PartyRole (role, party, profile) |
/v1/party-relationships |
GET | kadry | PartyRelationship (type, partyFrom, partyTo, attribute) |
/v1/locations |
GET | majątek, magazyn | Location (profile, identifier, owner, attribute, contained, type, category) |
/v1/document-references |
GET, POST, PATCH | kadry, magazyn | DocumentReference (profile, identifier, attribute, type, participant, statusDate, issueDateFrom) |
/v1/capabilities |
GET | kadry | Capability (identifier) |
/v1/grant-assignments |
GET | kadry | GrantAssignment (assignedTo, granted, basedOn, attribute, scope) |
/v1/employments |
GET | kadry | Employment (identifier, kind, employeeId) |
/v1/positions |
GET | kadry | Position (identifier) |
/v1/organization-units |
GET | kadry | OrganizationUnit (identifier) |
/v1/organization-assignments |
GET | kadry | OrganizationAssignment (identifier, employeeId, organizationUnitId) |
/v1/qualifications |
GET | kadry | Qualification (type wymagany, identifier, holder, number) |
/v1/professional-groups |
GET | kadry | ProfessionalGroup (identifier) |
/v1/employee-professional-groups |
GET | kadry | EmployeeProfessionalGroup (identifier) |
/v1/posting-instructions |
GET, POST | księgowość | PostingInstruction (identifier, symbol, owner) |
/v1/journal-entries |
GET | księgowość | JournalEntry (postingInstruction wymagany, symbol, owner) |
/v1/payments |
GET | księgowość | Payment (identifier, owner, attribute) |
/v1/registers |
GET | księgowość | Register (identifier, symbol, owner) |
/v1/accounting-variants |
GET | księgowość | AccountingVariant (identifier, owner) |
/v1/cost-carriers |
GET | księgowość | CostCarrier (identifier, owner, attribute) |
/v1/cost-assignments |
GET | księgowość | CostAssignment (costCenterNumber, costCarrierId, owner, year, month) |
/v1/formula-components |
GET | księgowość | FormulaComponent (identifier, type, owner, attribute, lastModified) |
/v1/fixed-assets |
GET | majątek | FixedAsset (identifier, owner, attribute, status) |
/v1/asset-components |
GET | majątek | AssetComponent (identifier, owner, attribute, status) |
/v1/fixed-asset-documents |
GET, POST, PATCH | majątek | FixedAssetDocument (identifier, owner, attribute, status) |
/v1/fixed-asset-documents/$document-content |
GET | majątek | treść dokumentu ruchu majątku (identifier, owner, attribute, format); definicja document-content |
/v1/fixed-asset-allocations |
GET | majątek | FixedAssetAllocation (category wymagany, owner, attribute) |
/v1/cost-centers |
GET | majątek | CostCenter (identifier, owner, attribute) |
/v1/product-definitions |
GET | magazyn | ProductDefinition (profile, category, identifier, productGroupId, dateFrom) |
/v1/inventories |
GET | magazyn | Inventory (location, product) |
/v1/inventory-documents |
GET, POST | magazyn | InventoryDocument (type wymagany, identifier, owner, attribute, status, fromLocation, participant, issueDateFrom, issueDateTo) |
/v1/return-documents |
POST | magazyn | ReturnDocument (wyszukanie zwrotów treścią żądania) |
/v1/purchase-orders |
GET | magazyn | PurchaseOrder (identifier, owner, attribute, status, period, issueDateFrom, issueDateTo) |
/v1/purchase-requisitions |
GET, POST | magazyn | PurchaseRequisition (identifier, owner, status, symbol, issueDateFrom, issueDateTo) |
/v1/invoices |
GET | magazyn | Invoice (category wymagany, identifier, owner, attribute, status, dateFrom, dateTo) |
/v1/reports |
POST | raporty | zlecenie raportu (202, executionId, encryptedSessionKey) — Tryb raportowy; definicje cost-calculation, product-level-cost-calculation |
Zapis POST może nieść przestrzeń identyfikatora w treści (identifier[].system; value jest opcjonalne — nadaje je system prowadzący): wskazuje ona wtedy instalację, która zarejestruje zasób, a pominięta — rozstrzyga profil (rejestracja zasobu). W PATCH parametr identifier=system|value wskazuje zasób do zmiany, więc jest konieczny. Zapis zwraca 200 OK z zasobem po stronie systemu prowadzącego (POST /v1/reports — 202 Accepted; zlecenie raportu nie rejestruje zasobu). Brak tras PUT i DELETE.
Pozostałe obszary taksonomii
Powiązanie numerów domen i grup (sprzedaż, produkcja, jakość, master data, field service itd.) z modelem danych i endpointami poza trasami z tabeli nie jest częścią tego Implementation Guide. Integracja w tych obszarach opiera się na osobnych kontraktach udostępnionych przez operatora API (APIM, dokumentacja projektowa), bez implikacji co do dostępności endpointów.