Majątek - Przykłady
Przykłady pokazują model kanoniczny majątku dla kartoteki środka trwałego, alokacji, ośrodka kosztów oraz dokumentu ruchu majątku. Format zgodny z konwencjami API.ERP: camelCase w JSON, identifier z system, a pola słownikowe jako CodeableConcept.
Referencje: zgodnie z konwencją Reference podstawą logiczną każdej referencji jest identifier (system + value) wraz z type zasobu docelowego. Pole reference (ścieżka typu FixedAsset/2235) nie jest dziś zwracane; display — tekst dla człowieka — pojawia się, gdy źródło go dostarcza.
Słowniki: systemy kodów pochodzą z plików docs/vs/assets/*.json i mają postać https://api-erp.kamsoft.pl/vs/assets/<slug> (np. fixed-asset-status, fixed-asset-allocation-dimension, fixed-asset-document-status).
Konwencje wspólne: listy mają kopertę { "items": [...], "nextToken": null } i paginację count/offset; zapis odpowiada kodem 200.
Przestrzenie identyfikatorów
Identyfikatory kartotek mają system w przestrzeni instalacji urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>; <klucz> jest inny dla każdej kartoteki (środki, komponenty, dokumenty, miejsca użytkowania, ośrodki kosztów, strony); rodzaj identyfikatora wynika z przestrzeni system. Zob. Identyfikacja i parametry wdrożenia. Firma (owner) jest identyfikowana NIP-em (https://gov.pl/nip).
W przykładach skrót <oid> oznacza urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>.
1. FixedAsset
Kartoteka środka trwałego — bez pól lokalizacji, MPK i osoby odpowiedzialnej (te utrzymuje FixedAssetAllocation).
GET /v1/fixed-assets?owner=https://gov.pl/nip|1234567890&status=https://api-erp.kamsoft.pl/vs/assets/fixed-asset-status|accepted HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Accept: application/json
Element items[]:
{
"resourceType": "FixedAsset",
"meta": { "lastModified": "2025-07-15T09:00:00" },
"identifier": [
{ "system": "<oid>", "value": "2235" },
{ "system": "<oid>", "value": "ST/2024/2235" },
{ "system": "<oid>", "value": "5901234567890" }
],
"owner": [
{ "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "1234567890" } }
],
"name": "Laptop Dell Latitude 5540",
"text": "491",
"comment": "Laptop służbowy działu IT",
"status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-status", "code": "accepted", "display": "Przyjęty" }] },
"type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-type", "code": "fixed-asset", "display": "Środek trwały" }] },
"quantity": { "value": 1 },
"acquisitionDate": "2024-06-01",
"acceptanceDate": "2024-06-15",
"initialValueBalance": { "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/assets/fixed-asset-deprecation-type", "code": "linear", "display": "Liniowa" }] },
"attribute": [
{ "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-attribute-type", "code": "schema", "display": "Schemat bazy danych" }] }, "value": { "valueString": "S01" } },
{ "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-attribute-type", "code": "price", "display": "Cena" }] }, "value": { "valueMoney": { "value": 4500.00, "currency": "PLN" } } }
]
}
quantity jest obiektem Quantity; text niesie klasyfikację KŚT. Kod fixed-asset w type pochodzi z systemu …/assets/fixed-asset-type, który nie jest dziś opublikowany.
2. FixedAssetAllocation
Rekord alokacji wskazuje środek przez fixedAsset lub komponent przez assetComponent, wymiar przez dimension, cel przez target, a rodzaj przypisania przez category — zgodnie z FixedAssetAllocation §4.
2.1 Podział sztuk na lokalizacje i rozliczenie na MPK
50 krzeseł jako jeden środek: 30 szt. w budynku A, 20 szt. w budynku B (category = fixed-asset-location); koszty przypisane do dwóch ośrodków kosztów (category = fixed-asset-cost-center; weight nie jest dziś wypełniany).
[
{
"resourceType": "FixedAssetAllocation",
"owner": [{ "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "1234567890" } }],
"category": [{ "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-allocation-category", "code": "fixed-asset-location", "display": "Miejsca użytkowania dla środków trwałych" }] }],
"fixedAsset": { "type": "FixedAsset", "identifier": { "system": "<oid>", "value": "1810" } },
"dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/allocation-dimension", "code": "location", "display": "Miejsce użytkowania" }] },
"target": { "type": "Location", "identifier": { "system": "<oid>", "value": "101" } },
"quantity": { "value": 30 },
"attribute": [{ "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-allocation-attribute-type", "code": "schema", "display": "Schemat bazy danych" }] }, "value": { "valueString": "S01" } }]
},
{
"resourceType": "FixedAssetAllocation",
"owner": [{ "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "1234567890" } }],
"category": [{ "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-allocation-category", "code": "fixed-asset-location", "display": "Miejsca użytkowania dla środków trwałych" }] }],
"fixedAsset": { "type": "FixedAsset", "identifier": { "system": "<oid>", "value": "1810" } },
"dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/allocation-dimension", "code": "location", "display": "Miejsce użytkowania" }] },
"target": { "type": "Location", "identifier": { "system": "<oid>", "value": "102" } },
"quantity": { "value": 20 }
},
{
"resourceType": "FixedAssetAllocation",
"owner": [{ "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "1234567890" } }],
"category": [{ "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-allocation-category", "code": "fixed-asset-cost-center", "display": "Ośrodki kosztów dla środków trwałych" }] }],
"fixedAsset": { "type": "FixedAsset", "identifier": { "system": "<oid>", "value": "1810" } },
"dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-allocation-dimension", "code": "cost-center", "display": "Ośrodek kosztów" }] },
"target": { "type": "CostCenter", "identifier": { "system": "<oid>", "value": "501" } }
},
{
"resourceType": "FixedAssetAllocation",
"owner": [{ "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "1234567890" } }],
"category": [{ "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-allocation-category", "code": "fixed-asset-cost-center", "display": "Ośrodki kosztów dla środków trwałych" }] }],
"fixedAsset": { "type": "FixedAsset", "identifier": { "system": "<oid>", "value": "1810" } },
"dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-allocation-dimension", "code": "cost-center", "display": "Ośrodek kosztów" }] },
"target": { "type": "CostCenter", "identifier": { "system": "<oid>", "value": "502" } }
}
]
Dla kategorii fixed-asset-location i fixed-asset-party API podaje dimension w systemie …/assets/allocation-dimension (nieopublikowany); dla fixed-asset-cost-center — w opublikowanym …/assets/fixed-asset-allocation-dimension. Kody są te same.
2.2 Osoba odpowiedzialna z miejscem użytkowania (participant)
Kategoria fixed-asset-party: target wskazuje osobę odpowiedzialną (Party), a miejsce użytkowania, w którym odpowiada za środek, trafia do participant[] (Reference do Location). Ten sam wzorzec obowiązuje dla komponentu: zamiast fixedAsset występuje assetComponent.
{
"resourceType": "FixedAssetAllocation",
"owner": [{ "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "1234567890" } }],
"category": [{ "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-allocation-category", "code": "fixed-asset-party", "display": "Osoby odpowiedzialne dla środków trwałych" }] }],
"fixedAsset": { "type": "FixedAsset", "identifier": { "system": "<oid>", "value": "2235" } },
"dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/allocation-dimension", "code": "responsible-party", "display": "Osoba odpowiedzialna" }] },
"target": { "type": "Party", "identifier": { "system": "<oid>", "value": "20" } },
"participant": [
{ "type": "Location", "identifier": { "system": "<oid>", "value": "210" } }
]
}
Powiązania miejsc użytkowania z ośrodkami kosztów (location-cost-center: target = CostCenter, relatedTarget = Location) i z osobami (location-party: target = Location, participant[] = Party) mają ten sam kształt i nie wskazują środka.
3. CostCenter
{
"resourceType": "CostCenter",
"id": "501",
"identifier": [
{ "system": "<oid>", "value": "501" },
{ "system": "<oid>", "value": "501-IT" }
],
"owner": [{ "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "1234567890" } }],
"symbol": "IT",
"partOf": { "type": "CostCenter", "identifier": { "system": "<oid>", "value": "500" } },
"openingYear": 2019,
"attribute": [{ "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/cost-center-attribute-type", "code": "schema" }] }, "value": { "valueString": "S01" } }]
}
4. FixedAssetDocument
Dokument zmiany miejsca użytkowania (symbol ZM) z pozycją. Rodzaj dokumentu niesie type (słownik fixed-asset-document-type) i symbol (string); status wewnętrzny — status ze słownika fixed-asset-document-status (open, closed, posted). PDF dokumentu i status obiegu zewnętrznego są dwoma osobnymi wpisami attachment[].
{
"resourceType": "FixedAssetDocument",
"id": "1001",
"meta": { "lastModified": "2025-07-28T14:00:00" },
"identifier": [
{ "system": "<oid>", "value": "1001" },
{ "system": "<oid>", "value": "ZM/2025/1001" }
],
"owner": [{ "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "1234567890" } }],
"type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-document-type", "code": "location-change", "display": "Zmiana miejsca użytkowania" }] },
"symbol": "ZM",
"issueDate": "2025-07-27",
"introducedDate": "2025-07-28",
"status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-document-status", "code": "closed", "display": "Zamknięty" }] },
"period": { "start": "2025-07-01", "end": "2025-07-31" },
"description": "Przeniesienie laptopa na nowe stanowisko",
"position": [
{
"positionNo": 1,
"fixedAsset": { "type": "FixedAsset", "identifier": { "system": "<oid>", "value": "2235" } },
"note": "(Schema: S01)",
"value": [
{ "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/value-item-type", "code": "document-reference" }] },
"valueReference": { "type": "Document", "identifier": { "system": "<oid>", "value": "77015" } } }
]
}
],
"attachment": [
{ "contentType": "application/pdf", "data": "<base64>", "creation": "2025-07-27T00:00:00" },
{ "title": "workflow-status",
"attribute": [{ "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/attachment-attribute-type", "code": "workflow-status" }] }, "value": { "valueString": "approved" } }] }
],
"attribute": [{ "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-document-attribute-type", "code": "schema", "display": "Schemat bazy danych" }] }, "value": { "valueString": "S01" } }]
}
Pozycja ma pola fromLocation, toLocation, responsibleParty, quantity (Quantity), które odczyt dziś nie wypełnia. Treść PDF pobiera się także osobno przez $document-content (§5.3).
5. Cykl życia dokumentu majątku
Model rozdziela dwie warstwy (zob. koncepcja integracji, §4 i §6): dokumenty (FixedAssetDocument) opisują ruchy i decyzje, a stan aktualny przypisań utrzymuje FixedAssetAllocation. Poniższa sekwencja pokazuje przekazanie skanu dokumentu OT, aktualizację statusu obiegu, pobranie treści i odczyt alokacji lokalizacji.
5.1 Przekazanie skanu dokumentu (POST)
Request:
POST /v1/fixed-asset-documents?owner=https://gov.pl/nip|1234567890&attribute=schema|S01 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
{
"resourceType": "FixedAssetDocument",
"identifier": [{ "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>" }],
"attachment": [
{
"contentType": "application/pdf",
"data": "<base64 skanu>",
"attribute": [
{ "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/attachment-attribute-type", "code": "workflow-system" }] }, "value": { "valueString": "OBIEG-KLIENTA" } }
]
}
]
}
identifier[].system (przestrzeń ewidencji majątku) oraz attachment[].data są wymagane — bez nich 400. Wartości identyfikatora nie podaje się: nadaje ją ewidencja (rejestracja zasobu). Pozostałe pola dokumentu nie są przetwarzane.
Response (200 OK):
5.2 Aktualizacja statusu obiegu (PATCH)
Status wewnętrzny dokumentu (open/closed/posted) nie jest zmieniany przez API — treść zawierająca tylko status zwraca 501. PATCH aktualizuje status obiegu zewnętrznego przekazany w attachment[].attribute[]; dokument wskazuje parametr identifier.
Request:
PATCH /v1/fixed-asset-documents?identifier=urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>|1002&owner=https://gov.pl/nip|1234567890&attribute=schema|S01 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
{
"resourceType": "FixedAssetDocument",
"attachment": [
{
"attribute": [
{ "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/attachment-attribute-type", "code": "workflow-status" }] }, "value": { "valueString": "approved" } },
{ "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/attachment-attribute-type", "code": "workflow-link" }] }, "value": { "valueString": "https://eod.example/doc/1002" } }
]
}
]
}
Response (200 OK):
5.3 Pobranie treści dokumentu ($document-content)
Request:
GET /v1/fixed-asset-documents/$document-content?identifier=urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>|1002&owner=https://gov.pl/nip|1234567890&attribute=schema|S01&format=blob HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Accept: application/json
Response (200 OK):
{
"resourceType": "FixedAssetDocument",
"attachment": [
{ "contentType": "application/pdf", "data": "<base64>" }
]
}
Gdy dokument nie ma treści, odpowiedź to 404.
5.4 Odczyt alokacji lokalizacji (GET)
Alokacje odczytuje się według rodzaju (category wymagany); filtrowanie po środku wykonuje klient po fixedAsset.identifier.
Request:
GET /v1/fixed-asset-allocations?category=https://api-erp.kamsoft.pl/vs/assets/fixed-asset-allocation-category|fixed-asset-location&owner=https://gov.pl/nip|1234567890 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Accept: application/json
Response (200 OK):
{
"items": [
{
"resourceType": "FixedAssetAllocation",
"owner": [{ "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "1234567890" } }],
"category": [{ "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/fixed-asset-allocation-category", "code": "fixed-asset-location", "display": "Miejsca użytkowania dla środków trwałych" }] }],
"fixedAsset": { "type": "FixedAsset", "identifier": { "system": "<oid>", "value": "2527" } },
"dimension": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/allocation-dimension", "code": "location", "display": "Miejsce użytkowania" }] },
"target": { "type": "Location", "identifier": { "system": "<oid>", "value": "310" } },
"quantity": { "value": 1 }
}
],
"nextToken": null
}