Przejdź do treści

AttendanceCredential (karta RCP)

AttendanceCredential (karta RCP) to zasób reprezentujący nośnik identyfikacji pracownika w systemie rejestracji czasu pracy – kartę MIFARE, tag NFC, brelok proximity lub kod kreskowy. Posiadacz to PartyRole w roli pracownika (employee). Pracownik może mieć wiele nośników jednocześnie; co najwyżej jeden aktywny ma rolę primary i jego numer odpowiada polu ID_RCP w KS-ZZL. Rozszerza DomainResource.

1. Zakres i zastosowanie

AttendanceCredential = jeden nośnik: employee (Reference PartyRole), identifier (id karty, numer karty, opcjonalnie kod kreskowy), technology, role, status, opcjonalnie validPeriod, issueDate, revocationDate.

  • Rejestr kart – lista kart po pracowniku, roli lub statusie; eksport do systemu vendora RCP przed synchronizacją terminali.
  • Identyfikacja zdarzenia – AttendanceRecord.credential wskazuje kartę, gdy vendor zna wyłącznie numer nośnika.
  • Karta główna – numer karty primary jest wartością ID_RCP pracownika, widoczną na Party w przestrzeni Party.RcpId. Integracje oparte wyłącznie o ID_RCP działają bez zmian.

Poza zakresem: kontrola dostępu fizycznego (strefy, uprawnienia do drzwi).

2. Zawartość (struktura)

Oprócz elementów DomainResource (id, resourceType, meta, owner, comment, category, status, type, contained, attribute):

Nazwa Kard. Typ Opis
identifier 1..* Identifier Id karty, numer karty i kod kreskowy – przestrzenie w §2b
employee 1..1 Reference(PartyRole) Pracownik – PartyRole (role=employee), identyfikator employee-{id} w przestrzeni PartyRole.Id
technology 0..1 CodeableConcept Technologia nośnika – słownik hr/attendance-credential-technology: mifare, nfc, proximity, barcode, other
role 1..1 CodeableConcept Rola karty – słownik hr/attendance-credential-role: primary, secondary
validPeriod 0..1 Period Okres ważności; start i end jako data rrrr-mm-dd; brak end = okres otwarty
issueDate 0..1 string Data wydania karty, rrrr-mm-dd
revocationDate 0..1 string Data unieważnienia karty, rrrr-mm-dd

Uwaga: status (z DomainResource) – słownik hr/attendance-credential-status: active, blocked. Przy zapisie opcjonalny. Wiązanie pola status nie jest zapisane w JSON Schema (pole pochodzi z DomainResource); walidacja należy do warstwy API.

Uwaga: pole id nie jest wypełniane – id karty w KS-ZZL zwracane jest w identifier (przestrzeń AttendanceCredential.Id). meta.lastModified pochodzi z daty ostatniej zmiany rekordu; dopóki zasób nie jest uzgodniony między systemami, meta.warning zawiera kod unreconciled (resource-warning).

Kody słownikowe przy zapisie są porównywane bez rozróżniania wielkości liter; dopuszczalny jest też kod podany wyłącznie w text.

2a. Operacje

GET /v1/attendance-credentials?employee=<przestrzeń PartyRole.Id>|employee-1001&status=https://api-erp.kamsoft.pl/vs/hr/attendance-credential-status|active&count=20&offset=0
Parametr Opis
identifier Jedna para system\|wartość w przestrzeni AttendanceCredential.Id, AttendanceCredential.RcpId albo AttendanceCredential.Barcode
employee Pracownik – para system\|wartość w przestrzeni PartyRole.Id (employee-{id})
status system\|kod ze słownika hr/attendance-credential-status
role system\|kod ze słownika hr/attendance-credential-role
count, offset Paginacja (domyślnie 20 / 0)

Pojedynczą kartę odczytuje się przez ?identifier=<przestrzeń AttendanceCredential.Id>|<id> – API nie ma tras z {id}.

Metoda Ścieżka Opis
POST /v1/attendance-credentials Przypisanie nowej karty do pracownika. Wymagane: numer karty (AttendanceCredential.RcpId w identifier), employee, role. Druga aktywna karta primary pracownika → 422.
PATCH /v1/attendance-credentials?identifier=<przestrzeń AttendanceCredential.Id>\|<id> Zmiana karty: status, role, validPeriod, technology, employee. Nieznana karta → 404.

Odpowiedź zapisu: HTTP 200 z { "items": [ <AttendanceCredential> ] } (jeden obiekt). Odczyt: { "items": [...], "nextToken": null }. Błędy w formacie z konwencji technicznych: zły format pola lub parametru, brak pola wymaganego → 400; odmowa systemu prowadzącego → 422.

Zmiana karty głównej to dwa kroki: PATCH dotychczasowej karty na secondary, potem PATCH (albo POST) nowej z rolą primary. Kroki nie są atomowe – w odwrotnej kolejności drugi zapis kończy się 422. API nie ma operacji $set-primary.

2b. Identyfikatory

Przestrzenie wdrożeniowe urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz> publikowane jako NamingSystem – zob. Identyfikacja i parametry wdrożenia.

Przestrzeń (klucz) Znaczenie Klucz referencyjny Skąd system
AttendanceCredential.Id Id karty w KS-ZZL; nadaje system prowadzący tak NamingSystem
AttendanceCredential.RcpId Numer karty (ID_RCP) – wymagany przy POST. Unikalny wśród kart aktywnych (status = active); karty zablokowane mogą powtarzać numer, więc wyszukiwanie ?identifier= może zwrócić kilka kart nie NamingSystem
AttendanceCredential.Barcode Kod kreskowy karty – opcjonalny, tylko razem z numerem karty nie NamingSystem

3. Reguły i relacje

  • employee wskazuje PartyRole w roli employee – posiadaczem nośnika jest rola, nie osoba.
  • W danej chwili pracownik ma co najwyżej jedną aktywną kartę primary; regułę pilnuje system prowadzący (druga → 422).
  • Numer karty jest unikalny wśród kart aktywnych – w danej chwili tylko jedna karta active ma dany ID_RCP. Numer może powtarzać się na kartach zablokowanych (np. karta zwrócona i wydana ponownie innemu pracownikowi). Dzięki temu numer karty jednoznacznie wskazuje pracownika przy imporcie zdarzeń.
  • Numer karty primary jest wartością ID_RCP pracownika – na Party w przestrzeni Party.RcpId. To relacja logiczna, nie referencja w JSON.
  • Karta blocked nie jest akceptowana przy imporcie zdarzeń – zdarzenie zostaje odrzucone (zob. AttendanceRecord).
  • AttendanceRecord.credential wskazuje ten zasób; w odpowiedzi API uzupełnia kartę pracownika, nawet gdy nadawca jej nie podał.
  • Między kartą a AttendanceTerminal nie ma referencji – wiąże je dopiero AttendanceRecord.

4. Odniesienia