Przejdź do treści

DocumentReference

DocumentReference (dokument) to generyczna koperta na treść biznesową: część główna (nagłówek) oraz position[] (segmenty), w stylu FHIR Observation.component. Identyfikacja przez Identifier, typ przez CodeableConcept, strony przez participant (Party / PartyRole), metadane i sumy m.in. w attribute[]. Wzorowany na OAGIS (BOD), UBL 2.3, SAP (nagłówek + pozycje), FHIR (DocumentReference, Composition), GS1.

Rozszerza DomainResource. Zasób w standardzie Kamsoft.FAIR (Fast Adaptive Interoperable Resources).

Charakter zasobu DocumentReference — rola uzupełniająca i transportowa

  • Charakter uzupełniający — DocumentReference nie zastępuje zasobów opisujących znane i zamodelowane procesy w API kanonicznym; pełna semantyka i reguły takich procesów są realizowane na dedykowanych zasobach i ich kontraktach (np. faktura i dekretacja → Invoice + PostingInstruction; ruch magazynowy → InventoryDocument).
  • Treść procesowa poza DocumentReference — nie należy traktować DocumentReference jako właściwego miejsca na dane biznesowe procesów, które mają już osobny model zasobu w API; DocumentReference może co najwyżej towarzyszyć lub powielać widok pomocniczy, nie jest „źródłem prawdy” dla tych procesów.
  • Brak weryfikacji i logiki procesowej po stronie API — payload DocumentReference nie jest rozliczany jak dokument procesowy: API nie prowadzi na jego podstawie pełnej walidacji reguł biznesowych procesu ani nie wykonuje na nim logiki typowej dla dedykowanych zasobów (np. księgowanie, zmiana stanów magazynowych). To nośnik / koperta, nie silnik procesu.
  • Pośrednik transportowy — pierwszeństwo ma przekazanie treści między systemami (integracja, synchronizacja, skrzynka nadawczo-odbiorcza i podobne mechanizmy w ERP), gdzie DocumentReference pełni rolę kanału ogólnego, a interpretacja i ewentualna obróbka następują w systemie nadawcy lub odbiorcy, nie jako scentralizowana logika API na DocumentReference.
  • Profil i przestrzeń — doprecyzowanie „co znaczy ten dokument” w danej integracji pozostaje po stronie profilu i umowy między systemami; IG opisuje kształt koperty, nie gwarantuje jednolitej semantyki procesowej jak przy zasobach dedykowanych.

1. Dwie części dokumentu: główna i position (pozycje)

  • Część główna – dane na poziomie dokumentu: identyfikatory, typ dokumentu, przestrzeń, status, data wystawienia, uczestnicy (participant), powiązane dokumenty, attribute[] (atrybuty, np. podsumowanie pozycji). Wspólna dla wszystkich przestrzeni; profile mogą dodawać pola (np. daty, kwoty zagregowane) tylko w części głównej.
  • Position (pozycje) – tablica position (0..), każdy element to jedna pozycja lub segment dokumentu (pozycja zamówienia, segment FK na DocumentReference poza dekretacją faktury, segment HR, segment CRM itd.). Każda pozycja ma code (CodeableConcept) – rodzaj segmentu – oraz w profilu danej przestrzeni zdefiniowaną strukturę (kwoty, ilości, konta, produkty, referencje). Podobnie jak w FHIR Observation: Observation ma component[], każdy component ma code (typ) i value[x] (wynik); tu DocumentReference ma position[], każda ma code (typ pozycji/segmentu), a szczegółowe właściwości (amount, quantity, account, product…) są definiowane w profilu dla danej przestrzeni i dla danego code*.

Pozostałe elementy części głównej: identyfikacja (identifier[]), type (z DomainResource – typ dokumentu), issueDate, uczestnicy (participant), powiązane dokumenty (basedOn), attribute[] – jak poniżej w tabeli. Wszystkie inne daty i pola domenowe należą do profilu. Referencje do produktu, kontrahenta, magazynu itd. w pozycjach dokumentu są w position → DocumentPosition → wybrana gałąź value[x] (często valueReference — zob. DocumentPosition, sekcje „Choice value[x]” i „Referencja do produktu”).

2. Zawartość (struktura)

Oprócz elementów DomainResource (id, meta, owner, comment, category, status, type, contained, attribute):

Nazwa Kard. Typ Opis
identifier 0..* Identifier Identyfikatory dokumentu (numer, origin-id, symbol systemu, numer korekty itd. – rodzaj w type); pole zasobu DocumentReference, nie rdzenia DomainResource
space 0..1 CodeableConcept Przestrzeń dokumentu (np. fk-inbox, eod, whs)
issueDate 0..1 date Data wystawienia (wspólna dla dokumentów)
participant 0..* Reference(Party lub PartyRole) + role (CodeableConcept) Uczestnicy dokumentu (wystawca, odbiorca, płatnik…); rola przy każdej referencji lub w osobnym polu w profilu
basedOn 0..* Reference(DocumentReference) lub Identifier Powiązane dokumenty (korekta, źródło, zamówienie)
position 0..* DocumentPosition Pozycje / segmenty dokumentu (wiersze, dekretacje, podsumowania VAT, segmenty HR/CRM…); struktura w DocumentPosition, szczegóły per przestrzeń w profilu
attachment 0..* Attachment Załączniki do dokumentu (skan, PDF, plik)

Uwaga: W rdzeniu DocumentReference są tylko pola uniwersalne dla wielu typów dokumentów (CRM, FK, WMS poza GR/GI, EOD, HR). Ruch magazynowy (GR, GI) nie jest wyrażany zasobem DocumentReference — wyłącznie InventoryDocument. Pola specyficzne dla danej przestrzeni definiuje profil — zob. sekcja 2a poniżej.

2a. Pola w profilach (nie w rdzeniu)
Dla dokumentów FK poza kanoniczną ścieżką faktury (np. dokument kasowy w buforze) profil może dodawać m.in.: paymentMethod, paymentAccount (Reference BankAccount), accountingDate, dueDate, receiptDate, saleDate, vatDate, ksefAcquisitionDate, totalAmount, splitPayment, register (CodeableConcept). Księgowanie faktury (dekretacja) — wyłącznie Invoice + PostingInstruction; DocumentReference nie uczestniczy w tym procesie. Dla zamówień i dokumentów HR stosuje się rdzeń DocumentReference i odpowiedni zestaw position oraz attribute[] / profil. Przyjęcie i wydanie towaru (GR / GI) oraz pozostałe ruchy magazynowe wyłącznie w InventoryDocument (movementType, fromLocation / toLocation, pozycje InventoryDocumentPosition).

3. Przestrzenie (CRM, FK, WHS, EOD, HR)

Tabela poniżej ma charakter ilustracyjny: pokazuje przykładowe powiązania typów dokumentów i kodów segmentów position[] z przestrzeniami, gdy DocumentReference pełni rolę koperty w profilu integracji. Nie stanowi rekomendacji, by dla procesów produkcyjnych lub kanonicznych w API preferować DocumentReference jako główny nośnik zamiast dedykowanych zasobów — patrz sekcja „Charakter zasobu DocumentReference — rola uzupełniająca i transportowa”.

Przestrzeń Przykłady typów dokumentów Position (segment) – przykłady code
CRM Oferta, zamówienie sprzedaży, umowa order-line, offer-line, contact-segment – w profilu: produkt, ilość, cena, termin realizacji
FK Dokument kasowy, dokument przychodzący (poza dekretacją faktury w kanonie API.ERP) W kanonie nie modeluje się dekretu faktury — wyłącznie PostingInstruction + Invoice; decree-line na DocumentReference nie jest częścią procesu księgowania faktury
WMS Dokumenty na DocumentReference (np. zapotrzebowania); GR / GI / MM / korekta stanów → wyłącznie InventoryDocument request-line, order-line (według profilu); ruch: InventoryDocument + InventoryDocumentPosition
EOD Dokument w obiegu, zatwierdzenie, wersja workflow-segment – powiązania z dokumentami źródłowymi
HR Dokument kadrowy, umowa o pracę, szkolenie hr-segment – w profilu: właściwości dla danej kategorii dokumentu HR

Dokument może być identyfikowany w więcej niż jednej domenie – wtedy identifier[] (np. wiele identyfikatorów z różnymi systemami) odzwierciedla te konteksty. W każdej domenie position z odpowiednim code i polami value* (DocumentPosition) oraz profilem modeluje pozycje i segmenty właściwe dla zamówienia, dokumentów księgowych, HR i CRM; attribute[] na nagłówku służy m.in. do podsumowania pozycji i metadanych domenowych.

4. Zgodność z systemami wzorcowymi

System Odpowiednik Uwagi
OAGIS BOD (ApplicationArea + Noun) Noun = typ dokumentu (PurchaseOrder…); ApplicationArea = identyfikatory, daty, nadawca
UBL 2.3 Order, DespatchAdvice, OrderResponse… Wspólne: ID, IssueDate, Party (AccountingSupplierParty, BuyerCustomerParty…), DocumentReference, LineItems
SAP Dokument FI/MM/SD Nagłówek (numer, typ, daty, odniesienia) + pozycje; typ dokumentu (BLART itd.)
FHIR DocumentReference, Composition DocumentReference = metadane + odniesienie do treści; Composition = struktura treści; DocumentReference u nas = dokument biznesowy (transakcja)
GS1 Business Document + SBDH Treść dokumentu (identyfikatory, strony, wiersze) + nagłówek routingu (SBDH)

5. Odniesienia