Przejdź do treści

Identifier

Identifier (identyfikator) to typ danych oznaczający wartość identyfikującą podmiot lub obiekt w ramach danego systemu lub autorytetu (np. NIP, REGON, numer kontrahenta, id wewnętrzne). Wzorowany na FHIR Identifier: jedna struktura dla wszystkich rodzajów identyfikatorów, bez osobnych pól (np. taxNo, regon) – rodzaj określa type (CodeableConcept) i system (URI).

1. Zakres i zastosowanie

Identifier służy do:

  • Identyfikacji stron – w Party: NIP, REGON, DUNS, BIC, id wewnętrzne, numer kontrahenta itd. jako elementy tablicy identifier[], każdy z type opisującym rodzaj.
  • Odniesień logicznych – w Reference pole identifier pozwala odwołać się do zasobu po identyfikatorze biznesowym, gdy nie ma literalnego URL.
  • Identyfikacji dokumentów, produktów, lokalizacji – symbol, numer, origin-id, GLN itd. – zawsze przez system + value oraz opcjonalnie type.

Reguła: system i value są podstawą identyfikacji; type (CodeableConcept) i use opisują znaczenie i przeznaczenie. W wielu kontekstach wymagane jest podanie przynajmniej value (oraz zwykle system lub type).

2. Zawartość (struktura)

Nazwa Kard. Typ Opis
use 0..1 code Przeznaczenie (np. official, usual, temp, secondary) – rozszerzalne
type 0..1 CodeableConcept Opcjonalny opis rodzaju identyfikatora (np. display tekstowy). Znaczenie wynika w praktyce z system (np. urn:pl:nip → NIP, system company → id wewnętrzny).
system 0..1 uri Przestrzeń nazw / autorytet wydający (np. urn:pl:nip, https://api-erp.kamsoft.pl/ns/company)
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

W praktyce system + value (lub type + value) są używane do jednoznacznego określenia identyfikatora; use i period uzupełniają kontekst.

3. Przykłady systemów (URI)

Przestrzeń nazw platformy api-erp.kamsoft.pl w formacie URL: https://api-erp.kamsoft.pl/ns/. Stąd np. https://api-erp.kamsoft.pl/ns/company, https://api-erp.kamsoft.pl/ns/origin. Rodzaj identyfikatora nie ma osobnego code systemu — wynika z system (np. urn:pl:nip, urn:pl:regon).

  • urn:pl:nip – NIP (PL)
  • urn:pl:regon – REGON
  • https://gov.pl/pesel – PESEL
  • https://gov.pl/nip – NIP (alternatywnie do urn:pl:nip)
  • https://ksef.mf.gov.pl/ – numer faktury nadany przez Krajowy System e-Faktur (KSeF); value = numer KSeF
  • https://api-erp.kamsoft.pl/ns/company – identyfikator w obrębie firmy (np. id kontrahenta)
  • https://api-erp.kamsoft.pl/ns/customer-number – numer kontrahenta (odbiorcy)
  • https://api-erp.kamsoft.pl/ns/origin-id – id w systemie źródłowym
  • HR (domenowe): hr-employee-id (identyfikator pracownika, globalny w instalacji), hr-employer-id (identyfikator pracodawcy/podmiotu – zalecane NFRM), integration-id (identyfikator w zintegrowanych systemach KS), hr-position-id, hr-organization-unit-id, hr-employment-id, hr-professional-group-id, time-and-attendance-id (np. nr karty RFID), barcode – pełna tabela w code-systems.
  • GLN, DUNS, BIC itd. – według rejestrów / standardów branżowych

5. Parametr zapytania identifier

W żądaniach GET na kolekcje zasobów (np. GET /v1/parties, GET /v1/invoices) parametr identifier służy do filtrowania wyników. Przekazywany jest jako lista par system|wartość, rozdzielonych przecinkami.

Przykład: ?identifier=system1|val1,system2|val2

Szczegóły formatu, logiki wyszukiwania (OR między identyfikatorami, AND z innymi filtrami) oraz implementacji: Konwencje techniczne — sekcja 12.4.

6. Odniesienia