Przejdź do treści

Document

Document (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 Document — rola uzupełniająca i transportowa

  • Charakter uzupełniający — Document 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 Document — nie należy traktować Document jako właściwego miejsca na dane biznesowe procesów, które mają już osobny model zasobu w API; Document 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 Document 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 Document 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 Document.
  • 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 Document 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 Document 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 (relatedDocument), 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 Document, 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
relatedDocument 0..* Reference(Document) 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)
statusDate 0..1 dateTime Data ostatniej zmiany statusu (uniwersalna dla dowolnego dokumentu)
expectedDate 0..1 date Oczekiwana data (np. realizacji, dostawy – zamówienie, WHS)
realizationDate 0..1 date Data realizacji (zamówienie, dostawa, WHS)

Uwaga: W rdzeniu Document 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 Document — 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; Document nie uczestniczy w tym procesie. Dla zamówień i dokumentów HR stosuje się rdzeń Document 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 Document pełni rolę koperty w profilu integracji. Nie stanowi rekomendacji, by dla procesów produkcyjnych lub kanonicznych w API preferować Document jako główny nośnik zamiast dedykowanych zasobów — patrz sekcja „Charakter zasobu Document — 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 Document nie jest częścią procesu księgowania faktury
WMS Dokumenty na Document (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; Document u nas = dokument biznesowy (transakcja)
GS1 Business Document + SBDH Treść dokumentu (identyfikatory, strony, wiersze) + nagłówek routingu (SBDH)

5. Odniesienia