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 (referencje do 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.
  • Position (pozycje) – tablica position (0..), każdy element to jedna pozycja lub segment dokumentu (pozycja zamówienia, podsumowanie VAT, segment kadrowy itd.). Każda pozycja ma code (CodeableConcept) – rodzaj segmentu – oraz listę wartości value[] (ValueItem). 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 wartości (kwoty, ilości, produkty, referencje…) idą w value[] z opcjonalnym type*.

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. Profile nie dodają pól; dane domenowe idą w attribute[] i position[]. Referencje do produktu, kontrahenta, magazynu itd. w pozycjach dokumentu są w position → DocumentPosition → element value[] z wariantem valueReference (zob. DocumentPosition, „Referencja do produktu”).

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: id dokumentu w przestrzeni DocumentReference.Id (dokument w skrzynce kadrowej albo dokument magazynowy; klucz referencyjny, system z NamingSystem), numer itd.; pole zasobu DocumentReference, nie rdzenia DomainResource
space 0..1 CodeableConcept Przestrzeń dokumentu – słownik document-space: hr (hr-inbox)
issueDate 0..1 string (data) Data wystawienia / dokumentu (ISO 8601)
participant 0..* Reference(PartyRole) Uczestnicy dokumentu (wystawca, nabywca, pracownik…) jako referencje do strony w roli; rola wynika z PartyRole.role
basedOn 0..* Reference(DocumentReference) Powiązane dokumenty (korekta, źródło, zamówienie)
position 0..* DocumentPosition Pozycje / segmenty dokumentu (wiersze, podsumowania VAT, segmenty kadrowe…); struktura w DocumentPosition
attachment 0..* Attachment Załączniki do dokumentu (skan, PDF, plik)

Uwaga: W rdzeniu DocumentReference są tylko pola uniwersalne dla wielu typów dokumentów (kadry, magazyn poza ruchem towaru, księgowość, CRM). Ruch magazynowy (przyjęcie, wydanie) nie jest wyrażany zasobem DocumentReference — wyłącznie InventoryDocument. Dane specyficzne dla przestrzeni idą w attribute[] ze słownika document-attribute-type: finance · hr · warehouse; type, status i category – słowniki document-type, document-status, document-category z segmentem dziedziny (zob. code-systems).

2a. Dane domenowe poza rdzeniem
Profile (§2b) zawężają jedynie category; nie dodają pól. Daty i kwoty dokumentu księgowego (forma płatności, termin płatności, data księgowania, sumy netto/VAT/brutto, symbol rejestru) wyraża attribute[] z finance/document-attribute-type. Księgowanie faktury (dekretacja) — wyłącznie Invoice + PostingInstruction; DocumentReference nie uczestniczy w tym procesie. Przyjęcie i wydanie towaru oraz pozostałe ruchy magazynowe wyłącznie w InventoryDocument (movementType, fromLocation / toLocation, pozycje).

2b. Profile dokumentu

Profil category Zastosowanie
HrInboxDocument hr-inbox-document dokument w skrzynce kadrowej
WarehouseDocument warehouse-document metryka dokumentu magazynowego 
GET /v1/document-references?profile=https://api-erp.kamsoft.pl/ns/StructureDefinition/HrInboxDocument

Bez profile odpowiedź zawiera dokumenty wszystkich obsługiwanych profili; w schematach profili category jest wymagane. Schematy: profile kanoniczne.

3. Operacje

Parametry filtrów mają postać system|value (attribute: code|value). Odpowiedź odczytu to koperta { "items": [...], "nextToken": null }, stronicowana parametrami count (domyślnie 20) i offset (domyślnie 0).

Operacja Parametry Odpowiedź
GET /v1/document-references profile, identifier, attribute[] (m.in. external-system-name|<nazwa>), type, participant (przestrzeń wewnętrzna Party), statusDate, issueDateFrom, count, offset 200 koperta z DocumentReference[] (skrzynka kadrowa)
POST /v1/document-references treść: DocumentReference (profil HrInboxDocument) z identifier[].system (zalecany, value opcjonalne) 200 { "message": "..." }; 422, gdy system źródłowy odrzucił dokument
PATCH /v1/document-references treść: DocumentReference (profil WarehouseDocument) z identifier (przestrzeń i id dokumentu), status i type – zmiana statusu dokumentu magazynowego 200 { "items": [...] }

Przestrzeń identyfikatora (identifier[].system) wskazuje skrzynkę rejestrującą dokument; pominięta, rozstrzyga profil (rejestracja zasobu). Przy rejestracji wartość nadaje system prowadzący.

Filtr kodowany type rozpoznaje się po czterech słownikach zadeklarowanych dla zasobu: hr/document-type, warehouse/document-type, warehouse/document-status i warehouse/document-category. Słownik finance/document-type opisuje treść dokumentów księgowych, ale nie jest zadeklarowany dla tego zasobu — filtr w tej przestrzeni kończy się 400.

Brak tras z {id} i operacji DELETE.

4. Przestrzenie i segmenty

Tabela poniżej ma charakter ilustracyjny: pokazuje 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ń Typy dokumentów Position (segment) – code
Kadry (space = hr-inbox) dokument w skrzynce kadrowej (hr/document-type – słownik wdrożeniowy) treść dokumentu w attachment[] i attribute[]; pozycje nieużywane
Magazyn metryka dokumentu magazynowego (warehouse/document-type) warehouse/document-position-type: order-line, vat-summary-line, goods-receipt-line, goods-issue-line; ruch towaru → InventoryDocument
Księgowość dokument poza dekretacją faktury (finance/document-type) finance/document-position-type: accounting-item, vat-summary; dekret faktury → PostingInstruction

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 value[] (DocumentPosition) modeluje pozycje i segmenty; attribute[] na nagłówku służy m.in. do podsumowania pozycji i metadanych domenowych.

5. 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)

6. Odniesienia