FixedAssetDocument
FixedAssetDocument (dokument ruchu majątku) reprezentuje zdarzenie biznesowe dotyczące środka trwałego lub jego komponentu: przyjęcie, wytworzenie, sprzedaż, likwidację, odpis, zmianę miejsca, zmianę wartości albo zmianę osoby odpowiedzialnej. W odróżnieniu od ogólnego DocumentReference, ten zasób ma dedykowane pola dla kwot majątkowych oraz pozycji odnoszących się bezpośrednio do środków i komponentów.
Rozszerza DomainResource.
1. Zakres i zastosowanie
FixedAssetDocument służy do:
- odczytu dokumentów ruchu majątku wraz z pozycjami,
- udostępniania powiązanego PDF (
$document-content), - przekazania skanu dokumentu do ewidencji majątku (
POST), - aktualizacji statusu obiegu zewnętrznego dokumentu (
PATCH).
2. Zawartość (struktura)
Oprócz elementów DomainResource (id, resourceType, meta, owner, comment, category, status, type, contained, attribute):
| Nazwa | Kard. | Typ | Opis |
|---|---|---|---|
| identifier | 0..* | Identifier | Identyfikatory dokumentu (§2b) |
| symbol | 0..1 | string | Symbol rodzaju dokumentu (np. OT, LT, ZM) |
| issueDate | 0..1 | date | Data wystawienia dokumentu |
| introducedDate | 0..1 | date | Data wprowadzenia do systemu |
| amount | 0..1 | Money | Kwota dokumentu |
| depreciationAmount | 0..1 | Money | Kwota umorzenia lub odpisu |
| period | 0..1 | Period | Okres, którego dotyczy dokument (dzień, miesiąc lub rok rozwinięty do start/end) |
| description | 0..1 | string | Opis biznesowy dokumentu |
| position | 0..* | struktura pozycji (§2a) | Pozycje dokumentu odnoszące się do środka lub komponentu |
| attachment | 0..* | Attachment | Załączniki: PDF dokumentu (contentType, data, creation) oraz wpis statusu obiegu (title = workflow-status, attribute[] — §2c) |
Schemat nie wymaga żadnego pola. type niesie rodzaj dokumentu (§2c), status — status wewnętrzny (open, closed, posted), owner — firmę (Reference do Party z NIP, system https://gov.pl/nip).
2a. Pozycja (position[], struktura zagnieżdżona)
Pozycje są częścią dokumentu: nie mają własnego endpointu ani identyfikatora.
| Nazwa | Kard. | Typ | Opis |
|---|---|---|---|
| positionNo | 0..1 | integer | Numer pozycji dokumentu |
| fixedAsset | 0..1 | Reference(FixedAsset) | Środek, którego dotyczy pozycja |
| assetComponent | 0..1 | Reference(AssetComponent) | Komponent, jeżeli operacja dotyczy składnika |
| fromLocation | 0..1 | Reference(Location) | Lokalizacja źródłowa dla przemieszczenia |
| toLocation | 0..1 | Reference(Location) | Lokalizacja docelowa dla przemieszczenia |
| responsibleParty | 0..1 | Reference(Party) | Osoba odpowiedzialna powiązana ze zmianą |
| quantity | 0..1 | Quantity | Ilość sztuk, której dotyczy pozycja |
| note | 0..1 | string | Dodatkowy opis pozycji |
| value | 0..* | ValueItem | Wartości pomocnicze pozycji: opcjonalny type i dokładnie jeden wariant value* |
Schemat pozycji nie wymaga żadnego pola. Odczyt wypełnia dziś positionNo, fixedAsset, assetComponent, note oraz value[] z jednym elementem type = document-reference i valueReference do dokumentu źródłowego; pozostałe pola pozostają w kontrakcie.
2b. Identyfikatory
Rodzaj identyfikatora niesie Identifier.system — przestrzeń instalacji urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz> (osobny klucz dla każdej przestrzeni) publikowana jako NamingSystem — zob. Identyfikacja i parametry wdrożenia oraz Identifier.
| Przestrzeń (klucz) | Znaczenie | Klucz referencyjny | Skąd system |
|---|---|---|---|
FixedAssetDocument.Id |
Id dokumentu ruchu majątku; używany w parametrze identifier operacji PATCH i $document-content |
tak | NamingSystem |
| — (osobna przestrzeń) | Numer dokumentu (np. OT/2025/1002) | nie | NamingSystem |
2c. Systemy kodowania (value sety)
| Pole | Value set | Kody |
|---|---|---|
type |
fixed-asset-document-type |
acceptance, write-off, liquidation, sale, purchase, production, location-change, value-change, component-transfer, inventory; API emituje ponadto responsible-change i investment-protocol, których słownik dziś nie publikuje |
status |
fixed-asset-document-status |
open, closed, posted |
position.value[].type |
https://api-erp.kamsoft.pl/vs/assets/value-item-type (adres w rejestrze, słownik nieopublikowany) |
document-reference |
attachment[].attribute[].code |
https://api-erp.kamsoft.pl/vs/assets/attachment-attribute-type (adres w rejestrze, słownik nieopublikowany) |
workflow-status, workflow-link, workflow-system (valueString) |
attribute[].code |
fixed-asset-document-attribute-type |
schema |
Pole symbol jest typu string; rejestr adresów przewiduje dla niego słownik https://api-erp.kamsoft.pl/vs/assets/fixed-asset-document-symbol, który nie jest opublikowany.
3. Operacje
| Metoda | Ścieżka | Opis |
|---|---|---|
| GET | /v1/fixed-asset-documents |
Lista dokumentów |
| GET | /v1/fixed-asset-documents/$document-content |
Treść dokumentu (PDF) |
| POST | /v1/fixed-asset-documents |
Przekazanie skanu dokumentu |
| PATCH | /v1/fixed-asset-documents |
Aktualizacja statusu obiegu zewnętrznego |
Wspólne parametry: owner = https://gov.pl/nip|<NIP>, attribute = schema|<schemat>.
3.1. GET /v1/fixed-asset-documents
| Parametr | Format | Opis |
|---|---|---|
identifier |
system\|value |
Id dokumentu w przestrzeni urn:oid:…<klucz> |
owner, attribute |
jw. | |
status |
system\|value |
system = https://api-erp.kamsoft.pl/vs/assets/fixed-asset-document-status |
count, offset |
integer | Paginacja (domyślnie 20 / 0) |
Odpowiedź 200: { "items": [FixedAssetDocument…], "nextToken": null }.
3.2. GET /v1/fixed-asset-documents/$document-content
Parametry (wszystkie w zapytaniu): identifier = <urn:oid:…<klucz>>|<id> (wymagany), owner, attribute, format (blob preferuje treść binarną). Odpowiedź 200: FixedAssetDocument z jednym attachment[] zawierającym contentType i data (base64); 404, gdy dokument nie ma treści. Definicja operacji: https://api-erp.kamsoft.pl/ns/OperationDefinition/document-content (JSON); karta wdrożenia wymienia ją w rest[].resource[].operation[].
3.3. POST /v1/fixed-asset-documents
Treść: FixedAssetDocument z identifier[].system (przestrzeń zalecana — wskazuje instalację rejestrującą dokument, pominięta rozstrzyga profil; value opcjonalne, nadaje je ewidencja) i attachment[].data (base64 skanu; wymagane). Brak treści załącznika → 400. Opcjonalnie attachment[].attribute[] z kodem workflow-system. Odpowiedź 200: { "result": "<komunikat ewidencji>" } — zasób nie jest zwracany.
3.4. PATCH /v1/fixed-asset-documents?identifier=…
Parametr identifier = <urn:oid:…<klucz>>|<id> (wymagany). Treść: FixedAssetDocument z attachment[].attribute[] zawierającym workflow-status (wymagany) i opcjonalnie workflow-link. Treść bez workflow-status i bez status zwraca 400; treść tylko ze status zwraca 501 — zmiana statusu wewnętrznego (open/closed/posted) nie jest dostępna przez API. Odpowiedź 200: { "result": "<komunikat ewidencji>" }.
4. Zgodność z systemami ERP
| System | Odpowiednik | Uwagi |
|---|---|---|
| SAP | Asset transaction document | Dokumenty OT, LT i przemieszczenia |
| Oracle Fixed Assets | Asset transaction | Przyjęcia, wycofania, transfery, adjustments |
| D365 | Asset journal / asset movement | Ruchy i aktualizacje środków trwałych |