ProductDefinition
ProductDefinition (definicja produktu) to zasób reprezentujący pozycję w katalogu – wzorzec towaru lub usługi (w tym szkoleniowej), bez danych konkretnej instancji (seria, partia, data ważności). Definicja zawiera identyfikatory katalogowe, nazwę, typ, status oraz attribute[] (Attribute: jednostka miary, stawka VAT, producent, grupa towarowa itd.). Wzorowany na UBL 2.3 (CatalogueLine / Item), SAP (Material master), FHIR (Medication – definicja).
Rozszerza DomainResource.
1. Zakres i zastosowanie
ProductDefinition to poziom „katalogu”: co to za produkt, jakie ma cechy wspólne dla wszystkich instancji. Nie ma tu numeru partii, numeru seryjnego ani daty ważności – te są cechami egzemplarza. Egzemplarz nie jest udostępniany przez API.ERP (brak endpointu); partia, seria i data ważności podróżują w attribute[] pozycji dokumentów i stanów magazynowych.
- Towar: atrybuty np.
unit-of-measure,vat-rate,producer,product-group. - Usługa: klasa
service; specyfika (czas trwania, kategoria, liczba uczestników) jest przenoszona w atrybutach, nie w osobnym typie.
W pozycjach InventoryDocument, PurchaseRequisition i Inventory referuje się ProductDefinition (katalog).
Ceny katalogowe przenosi contained[] — element ProductPricing (ProductPricing); identyfikatory biznesowe pozostają na ProductDefinition.
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 katalogowe: id produktu (przestrzeń ProductDefinition.Id, klucz referencyjny), numer katalogowy (przestrzeń ProductDefinition.Number), EAN (system = https://gov.pl/ean); przestrzenie wdrożeniowe urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz> z NamingSystem |
| name | 0..1 | string | Nazwa definicji produktu (np. „Produkt A”, „Szkolenie BHP”) |
Schemat nie wymaga żadnego pola. Pozostałe cechy niesie attribute[] (§3).
type (z DomainResource) niesie klasę produktu — źródło detaliczne stosuje słownik product-class, źródło magazynowe słownik warehouse/product-definition-type (medicine, blood, material, nutrition, cytostatic). status: active/inactive ze słownika warehouse/product-definition-status (magazyn) albo active w systemie https://api-erp.kamsoft.pl/vs/status (detal; adres w rejestrze, słownik nieopublikowany). category (magazyn): warehouse/product-definition-category.
3. Klasa produktu i konwencje atrybutów
Definicja produktu obsługuje wiele rodzajów towarów (leki, wyroby medyczne, preparaty krwi, żywność specjalnego przeznaczenia, kosmetyki, usługi, towary ogólne). Model pozostaje jednozasobowy z dyskryminatorem — tożsamość katalogowa, logistyka, wycena i finanse są wspólne dla wszystkich rodzajów, a klasa w polu type mówi, czym produkt jest. API nie wymusza pól per klasa: istnieje jeden schemat ProductDefinition, a strony klas opisują konwencje kodów atrybutów, nie profile maszynowe.
3.1. Dwie osie: klasa a kontekst
- Klasa produktu (
type) — podróżuje z produktem niezależnie od miejsca obsługi (lek jest lekiem w aptece, hurtowni i magazynie). - Kontekst operacyjny — gdzie produkt jest obsługiwany (apteka, hurtownia, magazyn szpitalny); wynika z systemu dziedzinowego i nie jest osobnym polem. Odbija się w tym, jakiego słownika klasy i atrybutów używa odpowiedź.
3.2. Klasy produktu (product-class)
| Klasa | Opis | Kluczowe cechy |
|---|---|---|
| medication | Produkt leczniczy (lek gotowy, galenowy, recepturowy, homeopatyczny, szczepionka, immunologiczny) | ATC, postać, dawka, kategoria dostępności |
| blood-product | Preparat / składnik krwi | grupa krwi, rodzaj (Rh) — na definicji w źródle magazynowym |
| medical-device | Wyrób medyczny | klasa (I/IIa/IIb/III), UDI-DI, jednostka notyfikowana, oznaczenie CE |
| ivd-medical-device | Wyrób medyczny do diagnostyki in vitro | odrębny reżim IVDR |
| dietary-supplement | Suplement diety | — |
| medical-food | Środek spożywczy specjalnego przeznaczenia medycznego | — |
| cosmetic | Kosmetyk | — |
| biocidal-product | Produkt biobójczy | — |
| service | Usługa | brak partii/serii/daty ważności/stanu magazynowego |
| general-good | Towar ogólny / materiał / opakowanie | bazowy zestaw ProductDefinition |
Źródło detaliczne emituje dziś klasy medication, medical-food, medical-device, service, general-good. Źródło magazynowe nie używa product-class; jego rodzaje (medicine, blood, material, nutrition, cytostatic) odpowiadają klasom medication, blood-product, general-good, medical-food.
3.3. Wymiary ortogonalne — atrybuty, nie klasy
Cechy przecinające wiele klas pozostają kodami attribute[].code ze słownika product-definition-attribute-type:
attribute.code |
Znaczenie | Słownik wartości |
|---|---|---|
intended-use |
przeznaczenie (ludzkie, weterynaryjne) | kody nadaje wdrożenie |
preparation-type |
sposób przygotowania leku | kody nadaje wdrożenie |
pharmaceutical-category |
kategoria regulacyjna leku | kody nadaje wdrożenie |
storage-condition |
warunek przechowywania | kody nadaje wdrożenie |
availability-category |
kategoria dostępności leku | product-availability-category (Rp, Rpw, Rpz, OTC, Lz) |
medical-device-class |
klasa wyrobu medycznego | medical-device-class (I, IIa, IIb, III) |
packaging-deposit |
kaucja za opakowanie zwrotne | valueString (np. 0.50 zł) |
Zasada rozstrzygająca: osobną klasę wprowadza się tylko wtedy, gdy rodzaj produktu ma inny reżim regulacyjny/procesowy. Cecha opcjonalna albo wymiar przecinający wiele rodzajów to atrybut.
3.4. Konwencje atrybutów klasy
Specyfika każdej klasy jest przenoszona w attribute[] (Attribute: code = rodzaj cechy, value = wartość). Strony klas zestawiają kody atrybutów, warianty value* i słowniki wraz z przykładem; nie są schematami — kompletność zestawu zależy od systemu źródłowego.
| Klasa | Konwencja i przykład |
|---|---|
| medication | ProductDefinition — medication |
| blood-product | ProductDefinition — blood-product |
| medical-device | ProductDefinition — medical-device |
| ivd-medical-device | ProductDefinition — ivd-medical-device |
Pozostałe klasy korzystają z cech wspólnych (unit-of-measure, vat-rate, producer, product-group) i atrybutów opisowych. Źródło magazynowe stosuje własny słownik cech warehouse/product-definition-attribute-type (m.in. form, dose, package, producer, country, jednostki miary i mnożniki, international-name, trade-name, material-type); źródło detaliczne — słownik ogólny oraz retail/product-definition-attribute-type (producer-country).
4. Operacje
| Metoda | Ścieżka | Opis |
|---|---|---|
| GET | /v1/product-definitions |
Katalog definicji produktów |
| Parametr | Format | Opis |
|---|---|---|
profile |
URL profilu | Zawęża do profilu (dziś jeden: …/StructureDefinition/ProductDefinition) |
identifier |
system\|value |
Id (urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>), numer katalogowy (osobna przestrzeń OID) lub https://gov.pl/ean\|<EAN> |
category |
system\|value |
Filtr: odpowiedź zawiera wyłącznie definicje z podaną kategorią. Rozpoznawane są oba słowniki zasobu: warehouse/product-definition-category (medications, materials, blood, cytostatics, nutrition) i retail/product-definition-category (catalog). Przestrzeń spoza tych słowników kończy się 400 |
productGroupId |
integer | Zawężenie do grupy produktowej katalogu |
dateFrom |
date | Zmienione od |
count, offset |
integer | Paginacja (domyślnie 20 / 0) |
Odpowiedź 200: { "items": [ProductDefinition…], "nextToken": null }. Zapis nie jest dostępny.
Każdy podany filtr jest stosowany do odpowiedzi albo odrzucany statusem 400 — żaden nie jest pomijany po cichu (konwencje §8.1).
5. Przykłady
- ProductPricing-Examples – ceny w contained ProductDefinition.
- Przykłady klas: strony z §3.4.
6. Odniesienia
- DomainResource, ProductPricing (ceny katalogowe), Attribute (attribute[]), DocumentPosition (valueReference → ProductDefinition)
- Identifier, CodeableConcept, Reference
- Systemy kodowania —
product-class,product-definition-attribute-type - Schemat: ProductDefinition.schema.json