Przejdź do treści

Identifier

Identifier (identyfikator) to typ danych oznaczający wartość identyfikującą podmiot lub obiekt w ramach danej przestrzeni nazw (np. NIP, REGON, id kontrahenta w kartotece). Wzorowany na FHIR R5 Identifier: jedna struktura dla wszystkich identyfikatorów, bez osobnych pól (np. taxNo, regon). Rodzaj identyfikatora niesie system — URI przestrzeni, w której value jest unikalne. type jest opcjonalną wskazówką o celu identyfikatora, gdy przestrzeń nie jest odbiorcy znana.

1. Zakres i zastosowanie

Identifier służy do:

  • Identyfikacji stron – w Party: NIP, REGON, id kontrahenta, id pracownika itd. jako elementy tablicy identifier[], każdy w innej przestrzeni system.
  • Odniesień logicznych – w Reference pole identifier pozwala odwołać się do zasobu po parze system + value, gdy nie ma literalnego URL.
  • Identyfikacji dokumentów, produktów, lokalizacji, zasobów HR – zawsze przez system + value.

Reguła: system i value identyfikują jednoznacznie; use i period opisują przeznaczenie i ważność; type nie jest potrzebny do rozpoznania rodzaju — rodzaj wynika z przestrzeni.

2. Zawartość (struktura)

Nazwa Kard. Typ Opis
use 0..1 string Przeznaczenie (official, usual, temp, secondary)
type 0..1 CodeableConcept Cel identyfikatora, gdy przestrzeń nie jest znana; wyłącznie kody FHIR identifier-type (system = http://terminology.hl7.org/CodeSystem/v2-0203, np. TAX), wiązanie rozszerzalne. Kody klasyfikują cel, nigdy zasób — nie ma kodu „id kontrahenta"
system 0..1 uri Przestrzeń nazw / autorytet wydający (https://gov.pl/nip albo przestrzeń wdrożeniowa urn:oid:...); w jej obrębie value jest unikalne
value 0..1 string Wartość identyfikatora
period 0..1 Period Okres ważności identyfikatora (start, end)
assigner 0..1 Reference Organizacja lub system przypisujący identyfikator – opcjonalnie

3. Rodzaj identyfikatora = przestrzeń system

Klasa przestrzeni system type Skąd wartość system
Rejestry publiczne https://gov.pl/nip, https://gov.pl/regon, https://gov.pl/pesel, https://gov.pl/ean, https://gov.pl/eu-tax, https://ksef.podatki.gov.pl; GLN, DUNS, BIC według standardów branżowych opcjonalnie kod v2-0203 (np. TAX dla NIP) stałe, wspólne dla wszystkich wdrożeń
Przestrzenie wdrożeniowe (identyfikatory wewnętrzne systemu prowadzącego) urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz> — <instalacja> to gotowy prefiks instalacji z parametrów wdrożenia, <klucz> wskazuje kartotekę (np. Party.Id, Invoice.Id, FixedAsset.Id) brak NamingSystem (GET /v1/naming-systems; Identyfikacja i parametry wdrożenia)

Każda strona zasobu wymienia, które przestrzenie (klucze) zasób niesie i które z nich są kluczem referencyjnym (nadają się do ?identifier=system|value). Przestrzeń https://api-erp.kamsoft.pl/vs/ zawiera słowniki, nie przestrzenie identyfikatorów.

Reguła praktyczna: stabilnym wymiarem dokumentacji jest system (klucz przestrzeni); jego konkretna wartość dla przestrzeni wdrożeniowych jest parametrem instalacji publikowanym jako NamingSystem. type nie służy do dopasowywania danych.

4. Przykłady

Identyfikator publiczny (NIP); type opcjonalne:

{
  "system": "https://gov.pl/nip",
  "value": "9542685559",
  "type": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "TAX" } ] }
}

Identyfikator wewnętrzny (kartoteka zatrudnień instalacji; system z NamingSystem, w IG placeholder urn:oid:2.999.1):

{
  "system": "urn:oid:2.999.1",
  "value": "10234"
}

W przykładach IG przestrzenie wdrożeniowe reprezentują placeholdery urn:oid:2.999.<n> (łuk OID 2.999 jest zarezerwowany do celów przykładowych) — legenda w przykładach. We własnej integracji należy podstawić wartości system z NamingSystem.

5. Parametr zapytania identifier

W żądaniach GET na kolekcje zasobów (np. GET /v1/parties, GET /v1/employments) parametr identifier służy do filtrowania wyników. Przyjmuje dokładnie jedną parę system|wartość; wartość z przecinkiem lub bez separatora | jest odrzucana ze statusem 400.

Przykład: ?identifier=https://gov.pl/nip|9542685559

Filtr identifier łączy się z pozostałymi parametrami zapytania spójnikiem AND.

6. Odniesienia