Przejdź do treści

Reference

Reference (referencja) to typ danych oznaczający odniesienie do innego zasobu – np. do Party, PartyRole, dokumentu, umowy. Kształt pól jest zgodny z ideą FHIR Reference (relacja jednokierunkowa źródło → cel), przy czym w Kamsoft.FAIR znaczenie logiczne referencji jest zawsze osadzone w identyfikatorze biznesowym — patrz § 1.

1. Zakres i zastosowanie

Referencja pozwala łączyć zasoby bez kopiowania ich treści.

Konwencja Kamsoft.FAIR: podstawą logiczną odniesienia jest zawsze identyfikator biznesowy — pole identifier (Identifier) z poprawnie ustawionym system i value (oraz w razie potrzeby type określający rodzaj zasobu docelowego). To ten identyfikator definiuje do czego powiązanie się odnosi w integracjach i systemach ERP, także gdy cel nie ma endpointu w API integratorów.

Dodatkowo mogą występować:

  • reference — literalna ścieżka lub URL (np. Party/123), opcjonalne uzupełnienie techniczne (np. wartość zwrócona przez API przy odczycie). Nie zastępuje znaczenia nadawanego przez identifier i nie jest samodzielną podstawą powiązania biznesowego w naszej konwencji.
  • display — tekst dla człowieka (np. nazwa kontrahenta); ułatwia prezentację, nie zastępuje identifier.

Reguła minimalna (zgodna z FHIR): przynajmniej jedno z pól reference, identifier, display musi być ustawione (chyba że referencja jest uzupełniona przez rozszerzenie). Przy wymianie danych biznesowych integrator powinien zapewnić identifier, aby referencja była jednoznaczna niezależnie od dostępności GET po polu reference.

2. Zakres API a wartości Reference

Zakres API wyznacza API udostępnione integratorom (Portal dla Integratorów (APIM) — specyfikacja OpenAPI). To API wprost prezentuje, jakie zasoby są dostępne oraz jakie operacje można względem nich wykonać — bez dodatkowych domysłów poza tą specyfikacją.

Reference w payloadzie wiąże z innym bytem: znaczenie biznesowe daje identifier (oraz zwykle type celu) — § 1; reference i display — § 3. W polach referencji mogą pojawić się odniesienia do typów zasobów, które:

  • nie mają opisu w tym Implementation Guide, oraz
  • nie mają zdefiniowanych endpointów w API dla integratorów.

Taka wartość referencji jest wtedy poprawna jako informacja o powiązaniu (przede wszystkim przez identifier biznesowy; opcjonalnie także reference zwrócone przez system źródłowy), ale nie oznacza, że integrator może pobrać zasób docelowy przez to API — bo ten typ nie występuje w udostępnionym zbiorze zasobów i operacji.

Praktycznie — rola pól w naszej konwencji:

  • identifier — to jest rdzeń referencji: system + value (np. NIP, numer w ERP, identyfikator z uzgodnionej przestrzeni). Po tym rozpoznajesz cel w integracji i w mapowaniach do systemów źródłowych; nie wymaga, żeby typ celu miał endpoint w API integratorów.
  • reference — dodatek techniczny, gdy znasz ścieżkę zwróconą przez API (np. Party/123) i chcesz ją powielić w payloadzie; wywołanie GET ma sens tylko jeśli ten zasób i operacja są w API integratorów.
  • display — tekst dla człowieka; nie zastępuje identifier.

Pełna definicja pól — § 1 oraz tabela w § 3.

Konwencje REST — Konwencje techniczne; modele FAIR w IG — Kamsoft.FAIR.

3. Zawartość (struktura)

Nazwa Kard. Typ Opis
identifier 0..1 Identifier Podstawa logiczna referencji w FAIR: identyfikator biznesowy (system + value)
type 0..1 uri Typ zasobu docelowego (np. Party, PartyRole) — wspiera jednoznaczność przy rozwiązywaniu identifier
reference 0..1 string Opcjonalne odniesienie literalne – URL względny (np. Party/abc) lub bezwzględny; uzupełnienie techniczne, nie zastępuje identifier w znaczeniu biznesowym
display 0..1 string Tekst do wyświetlania (np. nazwa strony)

4. Zasoby osadzone (contained)

Jeśli zasób docelowy nie ma niezależnej tożsamości w wymianie, umieszcza się go w polu contained zasobu nadrzędnego (zob. DomainResource). W Reference podaje się odniesienie lokalne #<id> — np. ProductDefinition/pd-good-001#pp-retail lub #pp-retail w obrębie tego samego payloadu.

5. Odniesienia