Koncepcja integracji ESM (środki trwałe) w API.ERP

Wersja draft.
Źródło wymagań: opis interfejsu integracyjnego KS-ESM z systemami klasy EOD (schemat EODESM). API.ERP jest interfejsem uniwersalnym; użycie przez EOD jest przykładowym scenariuszem.

1. Cel i zakres

1.1 Cel

Włączenie domeny ESM (środki trwałe / Fixed Asset Management) do API.ERP jako osobnej domeny z własnymi zasobami, operacjami i value setami. API ma służyć dowolnym klientom (system obiegu dokumentów, BI, moduł FK, aplikacje mobilne, inne systemy), a nie tylko EOD.

1.2 Zakres

Master data ESM: kartoteki majątku, miejsca użytkowania, ośrodki kosztów, komponenty, słowniki (rodzaje majątku, typy dokumentów), cechy.
Dokumenty ESM: dokumenty ruchu majątku (zakup, sprzedaż, likwidacja, przyjęcie, wytworzenie, odpisy, zmiana miejsca/wartości/osób, protokół inwestycji) z obsługą statusu w zewnętrznym systemie workflow (np. EOD).
Operacje: CRUD na zasobach, tworzenie dokumentów, ustawianie statusu w zewnętrznym workflow, pobieranie treści dokumentu (PDF).
Format: API wyłącznie w JSON. XML (legacy, np. ESM_DOK) pozostaje po stronie adaptera; w dokumentacji tylko jako odniesienie do mapowania.

2. Decyzje architektoniczne (ustalone)

Decyzja	Przyjęte rozwiązanie
Umiejscowienie ESM	Osobna domena – własny katalog Resources (ESM), osobna specyfikacja OpenAPI (np. API-ERP-Canonical-ESM.yaml).
Miejsce użytkowania (OSR)	Location z category (np. `usage-place`) – reuse zasobu Core, bez nowego zasobu UsagePlace.
Ośrodek kosztów (CKS)	Group z type/category `cost-center` – reuse Group (Controlling w taxonomii „via Group”), bez nowego zasobu CostCenter.
Przypisania STW/komponent – miejsce, MPK, osoby, źródła	Wyjęcie z FixedAsset i AssetComponent pól location, costCenter, responsibleParty (oraz ewentualnie quantity – zob. otwarte decyzje). Wszystkie przypisania w zasobie FixedAssetAllocation: subject (Reference FixedAsset \| AssetComponent), dimension (location / cost-center / responsible-party / funding-source), target (Location, Group, PartyRole, FundingSource), quantity, weight, initialValue, agreement (Reference Document). Jeden zasób przypisań obsługuje środki trwałe i komponenty.
Źródła finansowania	Osobny zasób FundingSource (słownik źródeł, np. NFZ, programy UE). Umowy finansowania (np. umowa z NFZ UPZ/3333/2026) jako Document (type np. funding-agreement); w FixedAssetAllocation (dimension=funding-source) opcjonalne pole agreement (Reference Document) oraz initialValue (Money).
Dokument ESM	Osobny zasób FixedAssetDocument (nie profil Document) – dedykowane ścieżki, operacje i schemat.
Status w systemie zewnętrznym (np. EOD)	Generic: pole externalWorkflowStatus + identyfikator systemu (EOD = jeden z systemów). Value set DocumentWorkflowStatus (shared, in_progress, approved, rejected). Bez nazwy „EOD” w API.
Model uniwersalny	Model ESM jest projektowany dla wielu konsumentów (system obiegu dokumentów, BI, moduły FK, aplikacje zewnętrzne); EOD jest jednym z nich. Wszystkie wymiary przypisań (location, costCenter, responsibleParty, fundingSource) należą do uniwersalnego modelu; żaden konsument nie ma odrębnych struktur w API.
Nazewnictwo value setów i pól	Od razu docelowe: DocumentWorkflowStatus, externalWorkflowStatus (bez „eod” w nazwach).

3. Zasoby (Resources)

3.0 Stan obecny modelu i cel zmiany

W aktualnym modelu (przed wprowadzeniem dynamicznych przypisań):

FixedAsset ma po jednym polu:
location → Reference Location (miejsce użytkowania),
costCenter → Reference Group (type=cost-center),
responsibleParty → Reference PartyRole (osoba odpowiedzialna),
quantity → liczba sztuk w kartotece.
AssetComponent ma: location → Reference Location, responsibleParty → Reference PartyRole.

Ograniczenie: nie da się modelować wielu lokalizacji z podziałem sztuk, wielu ośrodków kosztów z wagami ani wielu osób odpowiedzialnych – tylko jedna wartość na zasób (np. „50 krzeseł, 30 w budynku A, 20 w budynku B” nie ma naturalnego odwzorowania).

Cel zmiany – dynamiczna struktura przypisań:

Location: wiele lokalizacji z quantity (ile sztuk w danej lokalizacji).
CostCenter: wiele ośrodków kosztów z weight (udział procentowy / waga w rozksięgowaniu), opcjonalnie quantity.
ResponsibleParty: wiele osób z quantity (ile sztuk pod opieką danej osoby).
Ten sam mechanizm dla FixedAsset i AssetComponent – jeden zasób przypisań obsługuje oba (pole subject → Reference FixedAsset | AssetComponent).

Model ESM jest uniwersalny od początku – dla dowolnych konsumentów (system obiegu dokumentów, BI, moduły FK, aplikacje zewnętrzne). Żaden konsument nie ma odrębnych struktur w API; wszystkie wymiary przypisań należą do kanonicznego modelu.

3.1 Zasoby nowe (domena ESM)

Zasób	Opis	Źródło w legacy (EODESM)
FixedAsset	Kartoteka środka trwałego: identyfikatory, nazwa, numer, status (inwestycje/przyjęte/zamortyzowane/zlikwidowane/sprzedane), wartości (początkowa, umorzenie, księgowa), amortyzacja (stawki, rodzaj), rodzaj majątku (RSM), KST, ilość sztuk (quantity lub totalQuantity – zob. otwarte decyzje), daty (przyjęcia, likwidacji, nabycia), opcjonalnie kod kreskowy. Bez pól location, costCenter, responsibleParty – przypisania do miejsc, MPK i osób są w FixedAssetAllocation. Cechy: attribute[] (Core Attribute).	V_EOD_ESM_STW, STW_CST
AssetComponent	Komponent majątku: powiązanie z FixedAsset (partOf / fixedAsset), numer, nazwa, wartości (bilansowa, podatkowa), status (aktywny/nieaktywny), daty, kod kreskowy. Bez pól location, responsibleParty – przypisania są w FixedAssetAllocation (subject=AssetComponent). Cechy przez attribute[].	V_EOD_ESM_KMP, KMP_CST
FixedAssetAllocation	Przypisanie środka trwałego lub komponentu do wymiaru (lokalizacja, ośrodek kosztów, osoba odpowiedzialna, źródło finansowania): subject (Reference FixedAsset \| AssetComponent), dimension (location \| cost-center \| responsible-party \| funding-source), target (Reference: Location, Group, PartyRole lub FundingSource zależnie od dimension), quantity (sztuki – dla location i responsible-party; opcjonalnie dla pozostałych), weight (udział % – dla cost-center; opcjonalnie dla funding-source), initialValue (Money – dla dimension=funding-source), agreement (Reference Document – opcjonalnie, gdy finansowanie z konkretnej umowy). Opcjonalnie validFrom/validTo. Suma quantity lub initialValue per wymiar dla danego subject; walidacja do doprecyzowania.	STW_OSR, STW_CKS, STW_KNT, rozszerzenie o źródła
FundingSource	Źródło finansowania (słownik): id, identifier, name, status, type/category (value set FundingSourceType, np. nfz, eu-fund, state-budget, own-funds), partOf (hierarchia), attribute[]. Używane w FixedAssetAllocation (dimension=funding-source) jako target.	Słownik źródeł finansowania (jeśli w legacy)
FixedAssetDocument	Dokument ruchu majątku: typ (zakup, sprzedaż, likwidacja, przyjęcie, wytworzenie, odpisy, zmiana miejsca/wartości/osób, protokół inwestycji), daty (wystawienia, wprowadzenia), status wewnętrzny (otwarty/zamknięty/zaksięgowany), externalWorkflowStatus (system + status z DocumentWorkflowStatus), wartość/umorzenie, pozycje (referencje do FixedAsset/AssetComponent). Załącznik (PDF) przez attachment. Dokumenty OT/ZM mogą być źródłem zmian przypisań; stan aktualny jest utrzymywany w FixedAssetAllocation.	V_EOD_ESM_DOK, ESM_DOK, DOK_STW

3.2 Zasoby współdzielone (bez nowych zasobów)

Koncepcja legacy	Zasób API.ERP	Uwagi
Miejsce użytkowania (V_EOD_ESM_OSR)	Location	category/type np. `usage-place`; hierarchia przez partOf.
Ośrodek kosztów (V_EOD_ESM_CKS)	Group	type/category `cost-center`; partOf, identifier, name; rok otwarcia/zamknięcia w attribute.
Kontrahenci/pracownicy (V_EOD_ESM_KNT)	Party + PartyRole	Typ kartoteki (kontrahent/pracownik) przez PartyRole.type lub category.
Słownik cech (V_EOD_ESM_CST)	Attribute (definicje)	Definicje cech (typ: KWOT, TEXT, DATA, BOOL, LIST, …) przez Attribute/code system; wartości przy FixedAsset/AssetComponent w attribute[].
Rodzaj majątku (V_EOD_ESM_RSM)	Value set AssetType	Środki trwałe (S), wyposażenie (W), WNiP (P) – value set; ewentualnie mały zasób słownikowy.
Typ dokumentu (V_EOD_ESM_TDK)	Value set FixedAssetDocumentType	ZK, SP, LT, OT, WT, OD, ZM, ZW, ZO, PI – value set; ewentualnie zasób słownikowy.

3.3 Relacje

FixedAsset – kartoteka środka; bez bezpośrednich referencji do Location, Group, PartyRole; przypisania przez FixedAssetAllocation.
AssetComponent → FixedAsset (partOf / fixedAsset); przypisania (lokalizacja, osoby) przez FixedAssetAllocation (subject=AssetComponent).
FixedAssetAllocation → subject (FixedAsset lub AssetComponent); target zależnie od dimension: Location, Group (cost-center), PartyRole, FundingSource; opcjonalnie agreement (Document). Wymiary: location (quantity), cost-center (weight, opcjonalnie quantity), responsible-party (quantity), funding-source (initialValue, opcjonalnie weight, agreement).
FundingSource – słownik źródeł finansowania; używany jako target w FixedAssetAllocation (dimension=funding-source).
FixedAssetDocument → pozycje z Reference(FixedAsset), Reference(AssetComponent); dokumenty mogą powodować zmiany w FixedAssetAllocation (stan aktualny); optional link do zewnętrznego systemu (identifier z systemem).
Kontekst firmy/schematu (NIPF, SCHE): standardowy kontekst API (np. company_id, organization_id lub segment ścieżki / header) – ten sam wzorzec co w innych domenach API.ERP.

4. Operacje

4.1 Standardowe (CRUD)

GET|POST|PATCH /v1/fixed-assets
GET|POST|PATCH /v1/asset-components
GET|POST|PATCH /v1/fixed-asset-allocations
GET|POST|PATCH /v1/funding-sources
GET|POST|PATCH /v1/fixed-asset-documents
Odczyt Location (category = usage-place) i Group (type = cost-center) wg istniejących endpointów Core.

Wszystkie z obsługą kontekstu firmy/schematu (query, header lub segment) oraz filtrami (np. status, typ, data).

4.2 Operacje specyficzne dla FixedAssetDocument

Potrzeba	Operacja	Uwagi
Ustawienie statusu w zewnętrznym systemie workflow	`PATCH /v1/fixed-asset-documents/{id}` z polem externalWorkflowStatus (system + status) lub `POST /v1/fixed-asset-documents/{id}/$set-workflow-status` (body: system, status, opcjonalnie link)	Generic; EOD wywołuje z system = EOD.
Ustawienie statusu wewnętrznego dokumentu (przez workflow)	`PATCH /v1/fixed-asset-documents/{id}` z polem status (open / closed / posted)	Workflow może w tym samym wywołaniu ustawić zarówno externalWorkflowStatus, jak i status w API.ERP – zob. §4.3.
Pobranie treści dokumentu (PDF)	`GET /v1/fixed-asset-documents/{id}/$document-content` lub `GET /v1/fixed-asset-documents/{id}/attachments/{attachmentId}` z Accept: application/pdf lub base64	Dowolny klient (EOD, portal, BI).

Konwencje API.ERP: operacje niestandardowe z prefiksem $ (technical-conventions).

4.3 Dwukierunkowość statusów (FixedAssetDocument)

Statusy dokumentu muszą funkcjonować dwukierunkowo między API.ERP a systemem workflow (np. EOD):

Pole	Znaczenie	Kto ustawia / źródło prawdy
status	Status wewnętrzny dokumentu w API.ERP (open, closed, posted) – życie dokumentu w ESM.	API.ERP (ESM) oraz workflow – workflow może ustawiać status przy wywołaniu PATCH (np. po zatwierdzeniu ustawia status = closed lub posted).
externalWorkflowStatus	Status dokumentu w zewnętrznym systemie obiegu (shared, in_progress, approved, rejected).	Workflow – ustawiany przez system obiegu przy zmianie stanu w obiegu.

Kierunek Workflow → API.ERP:
Przy decyzji w obiegu (np. zatwierdzenie, odrzucenie) system workflow wywołuje PATCH /v1/fixed-asset-documents/{id} i w jednym żądaniu może ustawić: - externalWorkflowStatus (status w obiegu: approved / rejected / in_progress), - status (status w API.ERP: np. closed po zatwierdzeniu, aby odzwierciedlić w ESM, że dokument jest zamknięty).

Kierunek API.ERP → Workflow:
Gdy status dokumentu zmienia się w API.ERP (np. księgowanie w ESM ustawia status = posted), workflow musi móc to odczytać (GET dokumentu) i zsynchronizować swój widok. Ewentualnie API może udostępnić mechanizm powiadomień (webhook, lista dokumentów ze zmienionym statusem) – do doprecyzowania w implementacji.

Wymóg: PATCH FixedAssetDocument musi zezwalać na aktualizację zarówno externalWorkflowStatus, jak i status (w tym przez klienta zewnętrznego – workflow).

5. Value sets

Value set	Kontekst	Kody (propozycja)	Mapowanie legacy (SEOD/STAT/RODZ itd.)
AllocationDimension	FixedAssetAllocation.dimension	location, cost-center, responsible-party, funding-source	Wymiar przypisania (lokalizacja, MPK, osoba, źródło finansowania)
FundingSourceType	FundingSource.type / category	eu-fund, nfz, state-budget, own-funds, other	Typ źródła finansowania
DocumentWorkflowStatus	externalWorkflowStatus	shared, in_progress, approved, rejected	U, P, Z, O (EOD)
AssetStatus	FixedAsset.status	investment, accepted, depreciated, liquidated, sold	W, P, Z, L, S
AssetType	Rodzaj majątku (RSM/TYPM)	fixed-asset, equipment, wnip	S, W, P
DepreciationType	Rodzaj amortyzacji (RDZB, RDZP)	linear, linear-accelerated, linear-decelerated, declining, one-time, none	LN, LP, LS, DR, JR, BA
FixedAssetDocumentType	FixedAssetDocument.type	purchase, sale, liquidation, acceptance, production, write-off, location-change, value-change, responsible-change, investment-protocol	ZK, SP, LT, OT, WT, OD, ZM, ZW, ZO, PI
FixedAssetDocumentStatus	Status wewnętrzny dokumentu	open, closed, posted	O, Z, K
CharacteristicType (opcjonalnie)	Typ cechy (CST.TYPC)	amount, text, date, boolean, list, list-value, party-2, party-4	KWOT, TEXT, DATA, BOOL, LIST, LISTW, KNT2, KNT4

Typ dokumentu umowy finansowania: Umowy (np. z NFZ) są modelowane jako Document (Core). W value set dla typów dokumentu (Document.type) można dodać kod funding-agreement (umowa finansowania) – używany gdy FixedAssetAllocation.agreement wskazuje na Document reprezentujący konkretną umowę (np. UPZ/3333/2026).

W plikach value-sets/ (np. document-workflow-status.json, asset-status.json, allocation-dimension.json, funding-source-type.json) oraz wpis w docs/code-systems.md. Mapowanie na systemy źródłowe (np. SEOD) utrzymywać w sekcji ESM.

5a. Identyfikatory i system `company`

W przykładach (sekcja 12) w polu identifier używany jest system https://api-erp.kamsoft.pl/vs/company. Jest to przestrzeń nazw dla identyfikatorów wewnętrznych w API.ERP: wartość (value) to wewnętrzny numer/symbol nadany w kontekście firmy (np. numer kartoteki ST/2024/2235, symbol magazynu MAG-01, numer dokumentu ZM/2025/1001). Nie jest to „system EOD” ani system zewnętrzny – to standardowy w Implementation Guide sposób oznaczania identyfikatora wewnętrznego (company-scoped). Pełna lista systemów identyfikatorów i kodów: docs/code-systems.md.

6. Struktura dokumentu i pozycji FixedAssetDocument

Nagłówek: id, identifier[], type (FixedAssetDocumentType), issueDate, introducedDate (opcjonalnie), status (open/closed/posted), externalWorkflowStatus (system, status), amount, depreciationAmount, period (okres), description, meta, attachment[] (w tym PDF).
Pozycje: tablica pozycji; każda pozycja: fixedAsset (Reference), assetComponent (Reference, opcjonalnie), dla ZM: fromLocation, toLocation, responsibleParty (opcjonalnie), quantity (sztuki), note. Inne typy dokumentów – rozszerzenie w zależności od RODZ (np. ZW – wartości, ZO – osoby).

Dwie warstwy: Dokumenty (OT, ZM itd.) opisują ruchy i decyzje (np. przeniesienie X szt. z lokalizacji A do B). Stan aktualny przypisań (gdzie ile sztuk, które MPK z jaką wagą, kto odpowiedzialny) jest utrzymywany w FixedAssetAllocation. Realizacja dokumentu może powodować tworzenie lub aktualizację rekordów FixedAssetAllocation.

Dane wejściowe w API w JSON. XML (np. ESM_DOK) – tylko po stronie adaptera; w dokumentacji jako odniesienie do mapowania.

7. Kontekst firmy/schematu (NIPF, SCHE)

Wszystkie encje w legacy są w kontekście NIPF + SCHE. W API.ERP:

Stosować ten sam mechanizm kontekstu co w innych domenach (np. parametr zapytania company_id, organization_id, nagłówek lub segment ścieżki).
Nie nazywać tego „parametrem EOD” – to kontekst wielodostępowy / multi-company.

8. Scenariusz użycia: integracja z systemem EOD

Jako przykład wykorzystania uniwersalnego API:

EOD odczytuje fixed-assets, locations (usage-place), groups (cost-center), parties (kontrahenci/pracownicy), asset-components, słowniki – do list rozwijanych i walidacji.
EOD odczytuje fixed-asset-documents (lista dokumentów do obiegu).
EOD pobiera treść PDF: GET .../fixed-asset-documents/{id}/$document-content (lub attachment).
Po decyzji w obiegu EOD wywołuje PATCH .../fixed-asset-documents/{id} z externalWorkflowStatus (status w obiegu: approved/rejected/in_progress) oraz – w tym samym wywołaniu – z status (status w API.ERP: np. closed po zatwierdzeniu), zgodnie z dwukierunkowością statusów (§4.3).
EOD (lub inny system) tworzy dokument: POST /v1/fixed-asset-documents z payloadem JSON (np. zmiana miejsca – pozycje z fromLocation, toLocation, fixedAsset, quantity).

Mapowanie szczegółowe: EODESM (tabele, widoki, funkcje PL/SQL) → zasoby i operacje API.ERP – w osobnym rozdziale Implementation Guide (np. „Mapowanie EODESM → API.ERP”).

9. Kroki wdrożenia (propozycja)

Dokumentacja zasobów
docs/Resources/ESM/README.md – tabela zasobów i relacji.
docs/Resources/ESM/FixedAsset.md, AssetComponent.md, FixedAssetDocument.md – struktura pól, zgodność z SAP/Oracle/D365.
Core / reuse
W dokumentacji Location i Group: doprecyzować category/type usage-place i cost-center (w tym dla ESM).
Value sets i code systems
Pliki w value-sets/: DocumentWorkflowStatus, AssetStatus, AssetType, DepreciationType, FixedAssetDocumentType, FixedAssetDocumentStatus (opcjonalnie CharacteristicType).
Wpis w docs/code-systems.md oraz mapowanie na kody legacy.
OpenAPI i schemy
API-ERP-Canonical-ESM.yaml (lub w docs/openapi/): ścieżki /v1/fixed-assets, /v1/asset-components, /v1/fixed-asset-allocations, /v1/funding-sources, /v1/fixed-asset-documents oraz operacje $set-workflow-status, $document-content.
Generowanie JSON Schema (np. do schemas/canonical-esm/).
Domain taxonomy
W docs/domain-taxonomy.md: Group F (Assets & Field Service) – ESM/Asset Management oznaczony jako realizowany w API.ERP (zasoby ESM); aktualizacja roadmapy.
Canonical / nawigacja
W docs/canonical/README.md (lub odpowiedniku): sekcja ESM – mapowanie domena ESM → Resources/ESM → OpenAPI ESM.
Przykłady
docs/Examples/ESM-Examples.md (lub rozszerzenie istniejącego): JSON FixedAsset, FixedAssetAllocation (np. 50 krzeseł, źródła finansowania), FundingSource, FixedAssetDocument (np. ZM), externalWorkflowStatus, Location (usage-place), Group (cost-center).
Mapowanie legacy
Rozdział lub plik: EODESM (widoki, funkcje, tabele) → zasoby i operacje API.ERP (w tym EOD jako jeden z systemów w externalWorkflowStatus). Dopisać mapowanie dla FixedAssetAllocation i FundingSource (tabele/widoki przypisań, słowniki źródeł), jeśli występują w legacy.

Otwarte decyzje (do doprecyzowania w toku wdrożenia):

Quantity na FixedAsset: Czy pole quantity (totalQuantity) pozostaje na FixedAsset do wyświetlania i walidacji, czy łączna ilość wynika wyłącznie z sumy quantity w FixedAssetAllocation (dimension=location lub responsible-party)?
Nazwa zasobu przypisań: FixedAssetAllocation vs FixedAssetAssignment vs inna; spójność z CostAssignment (FK).
Reguły walidacji: Czy suma quantity per wymiar dla danego subject musi równać się totalQuantity środka? Czy suma weight dla cost-center / funding-source musi wynosić 100%?
Implementacja wymiarów: Czy w pierwszej implementacji wszystkie wymiary (location, cost-center, responsible-party, funding-source) muszą być obsługiwane w backendzie, czy dopuszczalne jest udostępnienie pełnego modelu w API z implementacją wybranych wymiarów w kolejnych etapach.

10. Diagram relacji (ESM)

flowchart TB
  FA[FixedAsset\nidentifier, name, number, status\nvalues, depreciation, assetType\nquantity, attribute[]]
  AC[AssetComponent\nfixedAsset, number, name\nstatus, values\nattribute[]]
  FAL[FixedAssetAllocation\nsubject, dimension\ntarget, quantity\nweight, initialValue\nagreement]
  FS[FundingSource\nidentifier, name\nstatus, type]
  FAD[FixedAssetDocument\ntype, issueDate, status\nexternalWorkflowStatus\nposition[], attachment[]]
  Loc[Location\ncategory: usage-place\npartOf]
  Grp[Group\ntype: cost-center\npartOf]
  PR[PartyRole\nresponsible]
  Doc[Document\numowa finansowania]

  FA -->|subject| FAL
  AC -->|subject| FAL
  FAL -->|target location| Loc
  FAL -->|target cost-center| Grp
  FAL -->|target responsible-party| PR
  FAL -->|target funding-source| FS
  FAL -->|agreement| Doc
  AC -->|fixedAsset| FA
  FAD -->|position.fixedAsset| FA
  FAD -->|position.assetComponent| AC
  FAD -->|position.fromLocation/toLocation| Loc

11. Odniesienia

Źródło: Opis interfejsu integracyjnego systemu KS-ESM z systemami klasy EOD (schemat EODESM), wersja 2025.02.0.0.
API.ERP: DomainResource, DocumentReference, Location, CostCenter, technical-conventions, domain-taxonomy.
Plan wzorcowy: HR-ZZL-organization-model-plan.

12. Przykłady zasobów (ilustracja koncepcji)

Poniżej po kilka przykładów JSON dla każdego rodzaju zasobu ESM. Format zgodny z konwencjami API.ERP (camelCase, identifier z system, CodeableConcept/coding). Wartości ilustracyjne.

12.1 FixedAsset (kartoteka środka trwałego)

Przykład 1 – środek trwały przyjęty (przypisania w FixedAssetAllocation):

Kartoteka środka bez pól location, costCenter, responsibleParty – te informacje są w rekordach FixedAssetAllocation (zob. przykłady w §12.2).

{
  "resourceType": "FixedAsset",
  "id": "fa-2235",
  "meta": { "lastModified": "2025-07-15T09:00:00Z" },
  "identifier": [
    { "system": "https://api-erp.kamsoft.pl/vs/company", "value": "ST/2024/2235" },
    { "system": "https://api-erp.kamsoft.pl/vs/barcode", "value": "5901234567890" }
  ],
  "name": "Laptop Dell Latitude 5540",
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/asset-status", "code": "accepted", "display": "Przyjęty" }] },
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/asset-type", "code": "equipment", "display": "Wyposażenie" }] },
  "quantity": 1,
  "acquisitionDate": "2024-06-01",
  "acceptanceDate": "2024-06-15",
  "initialValueBalance": { "value": 4500.00, "currency": "PLN" },
  "initialValueTax": { "value": 4500.00, "currency": "PLN" },
  "accumulatedDepreciationBalance": { "value": 562.50, "currency": "PLN" },
  "bookValueBalance": { "value": 3937.50, "currency": "PLN" },
  "depreciationRateBalance": 12.5,
  "depreciationTypeBalance": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/depreciation-type", "code": "linear", "display": "Liniowa" }] },
  "description": "Laptop służbowy, numer seryjny XYZ123",
  "attribute": [
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/characteristic", "code": "KST", "display": "Klasyfikacja KST" }] }, "valueString": "4-01-01" }
  ]
}

Przykład 2 – środek w inwestycji (uproszczony):

{
  "resourceType": "FixedAsset",
  "id": "fa-2527",
  "identifier": [{ "system": "https://api-erp.kamsoft.pl/vs/company", "value": "ST/2025/2527" }],
  "name": "Serwer rack HPE",
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/asset-status", "code": "investment", "display": "Inwestycje" }] },
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/asset-type", "code": "fixed-asset", "display": "Środek trwały" }] },
  "quantity": 1,
  "initialValueBalance": { "value": 25000.00, "currency": "PLN" },
  "depreciationTypeBalance": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/depreciation-type", "code": "linear", "display": "Liniowa" }] }
}

12.2 FixedAssetAllocation (przypisania – model uniwersalny)

Ten sam model służy wszystkim konsumentom API (system obiegu dokumentów, FK, BI, aplikacje zewnętrzne); żaden konsument nie ma odrębnych zasobów ani pól.

Przykład – 50 krzeseł jako jeden środek trwały: 30 szt. w budynku A, 20 szt. w budynku B; dwa MPK z wagami; dwie osoby odpowiedzialne z podziałem sztuk.

Rekordy FixedAssetAllocation dla FixedAsset „Krzesła” (id np. fa-krzesla):

[
  {
    "resourceType": "FixedAssetAllocation",
    "id": "fal-krzesla-loc-a",
    "subject": { "reference": "FixedAsset/fa-krzesla", "display": "Krzesła biurowe (50 szt.)" },
    "dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/allocation-dimension", "code": "location", "display": "Lokalizacja" }] },
    "target": { "reference": "Location/budynek-a", "display": "Budynek A" },
    "quantity": 30
  },
  {
    "resourceType": "FixedAssetAllocation",
    "id": "fal-krzesla-loc-b",
    "subject": { "reference": "FixedAsset/fa-krzesla", "display": "Krzesła biurowe (50 szt.)" },
    "dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/allocation-dimension", "code": "location", "display": "Lokalizacja" }] },
    "target": { "reference": "Location/budynek-b", "display": "Budynek B" },
    "quantity": 20
  },
  {
    "resourceType": "FixedAssetAllocation",
    "id": "fal-krzesla-cc-1",
    "subject": { "reference": "FixedAsset/fa-krzesla", "display": "Krzesła biurowe (50 szt.)" },
    "dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/allocation-dimension", "code": "cost-center", "display": "Ośrodek kosztów" }] },
    "target": { "reference": "Group/cks-it", "display": "IT" },
    "weight": 60
  },
  {
    "resourceType": "FixedAssetAllocation",
    "id": "fal-krzesla-cc-2",
    "subject": { "reference": "FixedAsset/fa-krzesla", "display": "Krzesła biurowe (50 szt.)" },
    "dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/allocation-dimension", "code": "cost-center", "display": "Ośrodek kosztów" }] },
    "target": { "reference": "Group/cks-admin", "display": "Administracja" },
    "weight": 40
  },
  {
    "resourceType": "FixedAssetAllocation",
    "id": "fal-krzesla-resp-jan",
    "subject": { "reference": "FixedAsset/fa-krzesla", "display": "Krzesła biurowe (50 szt.)" },
    "dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/allocation-dimension", "code": "responsible-party", "display": "Osoba odpowiedzialna" }] },
    "target": { "reference": "PartyRole/knt-jan", "display": "Jan Kowalski" },
    "quantity": 25
  },
  {
    "resourceType": "FixedAssetAllocation",
    "id": "fal-krzesla-resp-anna",
    "subject": { "reference": "FixedAsset/fa-krzesla", "display": "Krzesła biurowe (50 szt.)" },
    "dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/allocation-dimension", "code": "responsible-party", "display": "Osoba odpowiedzialna" }] },
    "target": { "reference": "PartyRole/knt-anna", "display": "Anna Nowak" },
    "quantity": 25
  }
]

Źródło finansowania – przypadek prosty (1000 zł z NFZ, bez umowy):

{
  "resourceType": "FixedAssetAllocation",
  "id": "fal-tomograf-nfz",
  "subject": { "reference": "FixedAsset/fa-tomograf", "display": "Tomograf XYZ" },
  "dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/allocation-dimension", "code": "funding-source", "display": "Źródło finansowania" }] },
  "target": { "reference": "FundingSource/fs-nfz", "display": "Narodowy Fundusz Zdrowia" },
  "initialValue": { "value": 1000.00, "currency": "PLN" }
}

Źródło finansowania – przypadek rozbudowany (5000 zł z umowy UPZ/3333/2026): Umowa jest zasobem Document; alokacja referuje ją przez agreement.

{
  "resourceType": "FixedAssetAllocation",
  "id": "fal-rtg-umowa-upz",
  "subject": { "reference": "FixedAsset/fa-rtg", "display": "Aparat RTG" },
  "dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/allocation-dimension", "code": "funding-source", "display": "Źródło finansowania" }] },
  "target": { "reference": "FundingSource/fs-nfz", "display": "Narodowy Fundusz Zdrowia" },
  "agreement": { "reference": "Document/doc-upz-3333-2026", "display": "Umowa UPZ/3333/2026" },
  "initialValue": { "value": 5000.00, "currency": "PLN" }
}

12.3 FundingSource (źródło finansowania)

{
  "resourceType": "FundingSource",
  "id": "fs-nfz",
  "identifier": [{ "system": "https://api-erp.kamsoft.pl/vs/company", "value": "NFZ" }],
  "name": "Narodowy Fundusz Zdrowia",
  "status": "active",
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/funding-source-type", "code": "nfz", "display": "NFZ" }] },
  "attribute": []
}

12.4 AssetComponent (komponent majątku)

Komponent bez pól location, responsibleParty – przypisania są w FixedAssetAllocation (subject=AssetComponent). Przykład: bateria zapasowa do laptopa.

{
  "resourceType": "AssetComponent",
  "id": "kmp-5264",
  "meta": { "lastModified": "2025-06-10T12:00:00Z" },
  "identifier": [{ "system": "https://api-erp.kamsoft.pl/vs/company", "value": "KMP/2235/5264" }],
  "fixedAsset": { "reference": "FixedAsset/fa-2235", "display": "Laptop Dell Latitude 5540" },
  "number": "BAT-001",
  "name": "Bateria zapasowa",
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/component-status", "code": "active", "display": "Aktywny" }] },
  "bookValueBalance": { "value": 350.00, "currency": "PLN" },
  "bookValueTax": { "value": 350.00, "currency": "PLN" },
  "acceptanceDate": "2024-06-15",
  "description": "Bateria oryginalna Dell",
  "attribute": []
}

Przypisania dla komponentu (FixedAssetAllocation, subject=AssetComponent): np. dwie lokalizacje (szt. w magazynie / przy stanowisku) i dwie osoby odpowiedzialne – rekordy jak w §12.2, z "subject": { "reference": "AssetComponent/kmp-5264" } oraz dimension location / responsible-party i quantity.

12.5 FixedAssetDocument (dokument ruchu majątku)

Przykład 1 – zmiana miejsca użytkowania (ZM) z pozycjami i statusem w zewnętrznym workflow:

{
  "resourceType": "FixedAssetDocument",
  "id": "fad-zm-1001",
  "meta": { "lastModified": "2025-07-28T14:00:00Z" },
  "identifier": [
    { "system": "https://api-erp.kamsoft.pl/vs/company", "value": "ZM/2025/1001" }
  ],
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/fixed-asset-document-type", "code": "location-change", "display": "Zmiana miejsca" }] },
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/fixed-asset-document-status", "code": "closed", "display": "Zamknięty" }] },
  "issueDate": "2025-06-27",
  "introducedDate": "2025-06-28",
  "description": "Przeniesienie laptopów do nowego biura",
  "externalWorkflowStatus": {
    "system": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/workflow-system", "code": "EOD", "display": "System obiegu dokumentów" }] },
    "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/document-workflow-status", "code": "approved", "display": "Zatwierdzony" }] },
    "updatedAt": "2025-07-28T13:45:00Z"
  },
  "position": [
    {
      "positionNo": 1,
      "fixedAsset": { "reference": "FixedAsset/fa-2235", "display": "Laptop Dell 5540" },
      "assetComponent": { "reference": "AssetComponent/kmp-5264", "display": "Bateria zapasowa" },
      "fromLocation": { "reference": "Location/osr-1", "display": "Biuro Katowice – piętro 2" },
      "toLocation": { "reference": "Location/osr-2", "display": "Biuro Katowice – piętro 3" },
      "responsibleParty": { "reference": "PartyRole/knt-20", "display": "Anna Nowak" },
      "quantity": 1,
      "note": "Przeniesienie na nowe stanowisko"
    },
    {
      "positionNo": 2,
      "fixedAsset": { "reference": "FixedAsset/fa-2527", "display": "Serwer rack HPE" },
      "fromLocation": { "reference": "Location/osr-3", "display": "Serwerownia A" },
      "toLocation": { "reference": "Location/osr-4", "display": "Serwerownia B" },
      "quantity": 1,
      "note": "Zmiana lokalizacji w ramach modernizacji"
    }
  ],
  "attachment": [
    { "contentType": "application/pdf", "url": "/v1/fixed-asset-documents/fad-zm-1001/$document-content", "title": "Dokument ZM/2025/1001" }
  ]
}

Przykład 2 – dokument w trakcie procedowania (uproszczony nagłówek):

{
  "resourceType": "FixedAssetDocument",
  "id": "fad-ot-1002",
  "identifier": [{ "system": "https://api-erp.kamsoft.pl/vs/company", "value": "OT/2025/1002" }],
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/fixed-asset-document-type", "code": "acceptance", "display": "Przyjęcie" }] },
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/fixed-asset-document-status", "code": "open", "display": "Otwarty" }] },
  "issueDate": "2025-07-20",
  "amount": { "value": 12000.00, "currency": "PLN" },
  "externalWorkflowStatus": {
    "system": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/workflow-system", "code": "EOD", "display": "System obiegu dokumentów" }] },
    "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/document-workflow-status", "code": "in_progress", "display": "Procedowany" }] }
  }
}

12.6 Location (miejsce użytkowania – reuse Core)

{
  "resourceType": "Location",
  "id": "osr-1",
  "identifier": [{ "system": "https://api-erp.kamsoft.pl/vs/company", "value": "OSR-001" }],
  "name": "Biuro Katowice – piętro 2",
  "status": "active",
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/location-type", "code": "usage-place", "display": "Miejsce użytkowania" }] },
  "category": [{ "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/location-category", "code": "usage-place", "display": "Miejsce użytkowania (ESM)" }] }],
  "partOf": { "reference": "Location/osr-0", "display": "Budunek Katowice" },
  "attribute": []
}

12.7 Group (ośrodek kosztów – reuse Core)

{
  "resourceType": "Group",
  "id": "cks-101",
  "identifier": [
    { "system": "https://api-erp.kamsoft.pl/vs/company", "value": "101" },
    { "system": "https://api-erp.kamsoft.pl/vs/cost-center-symbol", "value": "IT-INF" }
  ],
  "name": "IT – infrastruktura",
  "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/group-type", "code": "cost-center", "display": "Ośrodek kosztów" }] },
  "category": [{ "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/group-category", "code": "cost-center", "display": "Ośrodek kosztów (ESM)" }] }],
  "partOf": { "reference": "Group/cks-10", "display": "Dział IT" },
  "attribute": [
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/attribute", "code": "year-open", "display": "Rok otwarcia" }] }, "valueString": "2020" },
    { "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/attribute", "code": "year-close", "display": "Rok zamknięcia" }] }, "valueString": "" }
  ]
}

12.8 PATCH – ustawienie statusów (dwukierunkowość)

Fragment body dla PATCH /v1/fixed-asset-documents/fad-zm-1001 po zatwierdzeniu w systemie workflow (np. EOD). Workflow ustawia zarówno status w obiegu (externalWorkflowStatus), jak i status dokumentu w API.ERP (status):

{
  "externalWorkflowStatus": {
    "system": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/workflow-system", "code": "EOD" }] },
    "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/document-workflow-status", "code": "approved" }] },
    "link": "https://eod.example.com/case/12345"
  },
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/fixed-asset-document-status", "code": "closed", "display": "Zamknięty" }] }
}

Powyższe przykłady ilustrują strukturę zasobów, użycie externalWorkflowStatus (generic, z identyfikatorem systemu), dwukierunkowość statusów (status + externalWorkflowStatus w PATCH) oraz reuse Location i Group z odpowiednim category/type.