Przejdź do treści

DocumentPosition

DocumentPosition (segment/pozycja dokumentu) to typ opisujący jedną pozycję lub segment w ramach Document (tablica position[]). Ma pokrywać wszystkie przestrzenie: CRM, FK, WHS, HR, EOD – przy wspólnej warstwie abstrakcji (code, positionNo, opcjonalne wartości wspólne) oraz attribute i profilach dla właściwości specyficznych dla domeny. Wzorowany na FHIR Observation.component (code + value[x] + rozszerzenia).

DocumentPosition nie jest osobnym zasobem (DomainResource) – jest typem zagnieżdżonym w Document.

1. Cel: jedna struktura dla wielu przestrzeni

Wspólny zestaw pól pozwala bez mnożenia typów obsłużyć m.in.:

  • CRM – wiersz zamówienia (produkt, ilość, cena), segment oferty, kontakt.
  • FK – wiersz faktury (kwota, VAT, konto, wariant), dekret (konto Wn/Ma, kwota), linia podsumowania VAT (stawka, netto, VAT).
  • WHS – wiersz PZ/WZ (towar, ilość, magazyn, lokalizacja), przesunięcie.
  • HR – segment dokumentu kadrowego (szkolenie, umowa, uprawnienie itd.).
  • EOD – segment obiegu (powiązanie z dokumentem źródłowym, krok workflow).

Różnice między domenami są wyrażane przez code (rodzaj segmentu) oraz użycie pól value i attribute w profilu.

2. Zawartość (struktura)

Nazwa Kard. Typ Opis
code 1..1 CodeableConcept Rodzaj segmentu/pozycji (invoice-line, order-line, decree-line, vat-summary-line, goods-receipt-line, hr-segment itd. – system https://api-erp.kamsoft.pl/ns/document-position-type)
positionNo 1..1 integer Numer pozycji w dokumencie; unikalny w ramach dokumentu, numerowany od 1. Służy do referencji z zewnątrz (np. w danych księgowych).
valueQuantity 0..1 Quantity Jedna wartość niepieniężna (ilość szt., waga, czas – UCUM); dla kwot pieniężnych używać valueMoney
valueMoney 0..1 Money Jedna kwota pieniężna (value + currency); cena, kwota netto, suma itd.
valueItem 0..* ValueItem (jak Attribute: type + jedna z value*) Wiele wartości z typem: type (CodeableConcept, np. quantity, unit-price, net-amount, vat-amount) plus dokładnie jedno z: valueQuantity, valueMoney, valueString, valueInteger, valueBoolean, valueCodeableConcept, valueReference – spójne z AttributeValueItem w Attribute
valueAllocation 0..* AllocationItem Reguły alokacji kosztów: dla pozycji typu allocation-item – type (allocation-type: KR, KO, SB…) plus dokładnie jedno z: weights (składniki z kodem i wagą) lub costCarriers (nośniki kosztów). Kwoty do rozdzielenia w valueItem (allocation-item-type). Zob. Document-Examples §2b oraz plik Document-Accounting-Example.json.
valueCodeableConcept 0..* CodeableConcept Wartość kodowana: konto, stawka VAT, wariant dekretacji, status, typ (FK, CRM, WHS, HR)
valueReference 0..* Reference Odniesienia: definicja produktu (ProductDefinition), instancja produktu (Product), konto księgowe, rachunek bankowy (BankAccount), kontrahent (Party), magazyn, dokument, zasób (wspólne dla CRM, FK, WHS, HR)
valueString 0..1 string Tekst: opis, uwagi
status 0..1 CodeableConcept Status pozycji/wiersza (np. otwarta, zrealizowana, anulowana)
attachment 0..* Attachment Załączniki do pozycji (skan, plik)
attribute 0..* Attribute Właściwości specyficzne dla profilu (np. drugi numer konta, data dostawy, lokalizacja)

Uwaga: Ilości (szt., kg) – valueQuantity; kwoty pieniężne (cena, netto, VAT) – valueMoney. Dla wielu wartości z typem (ilość + cena jedn. + netto + VAT) – valueItem (każdy element: type CodeableConcept + valueQuantity | valueMoney | valueString itd. – jak AttributeValueItem w Attribute). Gdy pozycja wymaga wielu wartości innego typu (np. dwa konta w dekrecie), używa się valueCodeableConcept lub valueReference z konwencją/type, albo attribute. Szczegóły dla danego code i przestrzeni definiuje profil.

Referencja do produktu: Pozycja dokumentu odnosi się do pozycji katalogu lub do konkretnej instancji przez valueReference:

  • ProductDefinition – gdy wystarczy pozycja katalogu (np. zamówienie, faktura bez partii/serii): reference (np. ProductDefinition/123) lub identifier; opcjonalnie type = ProductDefinition, display = nazwa.
  • Product – gdy wymagana jest konkretna instancja (partia, numer seryjny, data ważności, np. PZ/WZ z partią, reklamacja z serią): reference (np. Product/456) lub identifier; opcjonalnie type = Product, display = nazwa lub identyfikator partii/serii.

W jednej pozycji (position) może być kilka valueReference (produkt/definicja, kontrahent, magazyn itd.); konwencja lub profil ustala, który element odnosi się do produktu (np. pierwsza referencja przy order-line, invoice-line, goods-receipt-line, lub referencja z type=ProductDefinition / type=Product).

3. Mapowanie: przestrzeń → code → pola

Poniższa tabela pokazuje, jak ten sam DocumentPosition jest używany w różnych przestrzeniach i dla różnych code. Dla każdego wiersza: które pola value*/attribute są typowo używane.

Przestrzeń code (przykład) valueQuantity valueItem valueCodeableConcept valueReference valueString attribute / profil
CRM order-line ilość lub cena (jedna) ilość + cena (gdy obie) status linii produkt, kontrahent opis data dostawy, jednostka
CRM offer-line ilość lub cena (jedna) ilość + cena (gdy obie) typ pozycji produkt opis ważność oferty
FK invoice-line – ilość, cena jedn., netto, VAT stawka VAT, wariant produkt, kontrahent opis odliczenie VAT
FK decree-line kwota – konto Wn, konto Ma – opis –
FK vat-summary-line – netto, VAT (po stawce) stawka VAT, odliczenie – – –
WHS goods-receipt-line ilość – jednostka, typ produkt, magazyn, lokalizacja uwagi data ważności, partia
WHS issue-line ilość – jednostka produkt, magazyn uwagi zlecenie, koszt
WHS transfer-line ilość – – produkt, magazyn z/do, lokalizacja – –
HR hr-segment – – typ segmentu, status pracownik, szkolenie, umowa treść daty, uprawnienia (profil)
EOD workflow-segment – – status kroku dokument źródłowy komentarz data, użytkownik (profil)

Dzięki temu jeden typ DocumentPosition z opcjonalnymi valueQuantity, valueItem, pozostałymi value i attribute pokrywa CRM, FK, WHS, HR i EOD; profile ustalają, które pola są wymagane i jakie code są dozwolone.

4. Zgodność z systemami wzorcowymi

System Odpowiednik pozycji/segmentu Uwagi
UBL 2.3 InvoiceLine, OrderLine, DespatchLine… ID, Quantity, LineExtensionAmount, Item (Reference), Price; mapowanie na code + valueQuantity + valueReference
OAGIS Line w BOD (np. PurchaseOrderLine) Quantity, Amount, ItemID, Party; odpowiednik code + value*
SAP Pozycja dokumentu (FI line, MM/SD item) Kwota, konto, materiał, magazyn; odpowiednik valueQuantity, valueCodeableConcept, valueReference
FHIR Observation.component code + value[x] (jedna wartość na component); u nas valueQuantity (jedna) lub valueItem (wiele typowanych) + valueCodeableConcept, valueReference, valueString + attribute

5. Odniesienia