Party (strona)
Model Party (strona) reprezentuje podmiot biorący udział w procesach biznesowych – organizację, osobę lub rolę (odbiorca, dostawca, płatnik, przewoźnik itd.). Jest wspólnym wzorcem dla kartotek i ról w systemach ERP (księgowość, kadry, magazyn, CRM), spójnym z podejściem OAGIS, UBL 2.3, GS1, ISO 20022, SAP MDG, Oracle Fusion, Microsoft CDM i Salesforce Data Cloud.
Party rozszerza DomainResource (id, resourceType, meta, owner, comment, category, status, type, contained, attribute) o atrybuty identyfikacji, nazwy, adresów, kontaktów i hierarchii. Role strony są modelowane w PartyRole, który referuje do Party przez party.
1. Zakres i zastosowanie
Party to zasób domenowy opisujący „kto" w procesach biznesowych:
- Identyfikacja – wiele identyfikatorów (NIP, REGON, numer VAT UE, identyfikator wewnętrzny, numer kontrahenta itd.) w pojedynczej strukturze Identifier
- Właściciel zasobu - Owner – wskazuje właściciela zasobu poprzez referencję do Party. Referencja do Party może być realizowana za pomocą dowolnego identyfikatora (np. NIP-u).
- Nazwa – name jako CodeableConcept (nazwa kodowana / wielojęzyczna)
- Adresy – lista Address z typem/użyciem (fizyczny, pocztowy, rozliczeniowy, dostawy)
- Kontakt – lista ContactPoint (telefon, email, faks, web)
- Hierarchia – partOf wskazuje stronę nadrzędną (np. jednostka w organizacji)
- Role – modelowane w PartyRole: PartyRole referuje do Party przez party. Ta sama Party może mieć wiele PartyRole (różne role). Relacja między dwiema stronami jest opisana przez PartyRelationship (partyFrom, partyTo).
- Status i klasyfikacja – dziedziczone z DomainResource: status (active/inactive/deleted), category (rodzaj strony, segment, grupa)
W platformie ERP Customer i Vendor (oraz opcjonalnie Contact, Organization) są profilami lub widokami Party – ta sama Party może być jednocześnie klientem i dostawcą przez wiele PartyRole.
2. Struktura (pola)
Poza polami z DomainResource (id, resourceType, meta, owner, comment, category, status, type, contained, attribute):
| Nazwa | Kard. | Typ | Opis |
|---|---|---|---|
| identifier | 0..* | Identifier | Identyfikatory strony: NIP, REGON, numery wewnętrzne itd. (system + value); przestrzenie – zob. §2b |
| name | 0..1 | CodeableConcept | Nazwa / firma – nazwa wyświetlana lub ustrukturyzowana |
| number | 0..1 | string | Numer strony |
| address | 0..* | Address | Adresy; typ przez Address.use / type (np. physical, postal, billing) |
| contactPoint | 0..* | ContactPoint | Dane kontaktowe (telefon, faks, email, web); typ każdego jako CodeableConcept |
| partOf | 0..1 | Reference(Party) | Strona nadrzędna – hierarchia organizacji (partOf → inny Party) |
Uwaga: Party NIE zawiera referencji do PartyRole. To PartyRole referuje do Party przez party (strona w roli). Rachunki bankowe kontrahenta są dostarczane w contained jako BankAccount.
2a. Profile strony
Jeden zasób Party ma cztery profile (StructureDefinition): Employee (pracownik), Employer (pracodawca, własna organizacja), Contractor (kontrahent: dostawca, odbiorca, płatnik) i AssetHolder (dysponent majątku). Profil rozpoznaje się po meta.profile oraz po category ze słownika party-kind (employee, employer, contractor, asset-holder), które nadaje API.ERP; w schematach profili category jest wymagane. Schematy profili: profile kanoniczne.
GET /v1/parties?profile=https://api-erp.kamsoft.pl/ns/StructureDefinition/Contractor&identifier=urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>|<id>
GET /v1/parties?profile=https://api-erp.kamsoft.pl/ns/StructureDefinition/Employee&count=50
Bez profile odpowiedź zawiera strony wszystkich obsługiwanych profili. Zapis (POST, PATCH) obsługuje profil Contractor (kartoteka kontrahenta w księgowości); przy zapisie podaj meta.profile albo category z party-kind – zasób bez rozpoznanego profilu nie zostanie przyjęty.
2b. Identyfikatory
Rodzaj identyfikatora niesie Identifier.system: rejestr publiczny albo przestrzeń wdrożeniowa urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz> publikowana jako NamingSystem — zob. Identyfikacja i parametry wdrożenia oraz Identifier. Identifier.type nie jest wymagane (opcjonalnie kod FHIR v2-0203, np. TAX dla NIP).
| Przestrzeń (klucz) | Znaczenie | Klucz referencyjny | Skąd system |
|---|---|---|---|
https://gov.pl/nip, https://gov.pl/regon, https://gov.pl/eu-tax |
NIP, REGON, numer VAT UE | tak — m.in. referencje owner przez NIP |
rejestr publiczny |
https://gov.pl/pesel |
PESEL (profil Employee) |
nie | rejestr publiczny |
Party.Id |
Id kontrahenta — kartoteka księgowości (profil Contractor) |
tak | NamingSystem |
Party.Id |
Id kontrahenta w dokumentach magazynowych (profil Contractor); kopia, nie kartoteka |
nie | NamingSystem |
Party.Id |
Id pracownika (profil Employee) |
tak | NamingSystem |
Party.Id |
Id organizacji — pracodawcy (profil Employer); dzieli przestrzeń z pracownikami |
nie | NamingSystem |
Party.Id |
Id strony w ewidencji majątku (profil AssetHolder) |
tak | NamingSystem |
Każdy profil ma własną przestrzeń Party.Id (osobny NamingSystem). Numer kontrahenta / numer strony jest polem number, nie identyfikatorem.
Przy tworzeniu strony podaj identifier z samą przestrzenią, bez value: numer nadaje system prowadzący i zwraca go w odpowiedzi. Przestrzeń jest opcjonalna — podana, wskazuje instalację, która stronę zarejestruje; pominięta, rozstrzyga profil. POST zawsze tworzy nową stronę; aktualizacja istniejącej to PATCH /v1/parties?identifier=<przestrzeń>|<wartość>&owner=https://gov.pl/nip|<NIP> (oba parametry wymagane). Szczegóły: rejestracja zasobu.
Identyfikatory branżowe (DUNS, BIC, GLN) używają system według rejestrów/standardów branżowych; zob. Identifier i code-systems.
2c. Systemy kodowania (value sety)
Value sety pól kodowanych Party (rejestr: Systemy kodowania i value sety).
Siła wiązania: wymagany — kod musi pochodzić ze słownika; rozszerzalny — kod ze słownika, jeśli pasuje, w przeciwnym razie własny kod z własnym system; przykładowy — kody wyłącznie ilustracyjne.
| Pole | Value set | Siła wiązania |
|---|---|---|
status |
party-status (active, inactive, deleted) |
wymagany |
type |
party-type: finance · assets · hr |
wymagany |
category |
party-kind (rodzaj strony, nadawany przez API.ERP) · party-category |
rozszerzalny |
name |
party-name: finance · warehouse · assets · hr |
przykładowy |
attribute[].code |
party-attribute-type: finance · warehouse · assets |
rozszerzalny |
Pola typów danych mają własne słowniki kanoniczne: address.use/address.type/address.component[].type (Address) oraz contactPoint (ContactPoint) — zob. rejestr (address-use, address-type, address-component-type, contact-point-system).
3. Operacje
Parametry filtrów mają postać system|value (attribute: code|value). Odpowiedź odczytu to koperta { "items": [...], "nextToken": null }, stronicowana parametrami count (domyślnie 20) i offset (domyślnie 0).
| Operacja | Parametry | Odpowiedź |
|---|---|---|
GET /v1/parties |
profile, type, identifier, owner, attribute[], status, lastModified, count, offset |
200 koperta z Party[] |
POST /v1/parties |
treść: Party (profil Contractor) z identifier[].system (zalecany, value opcjonalne); owner (opcjonalny) |
200 utworzona Party z nadanym identyfikatorem |
PATCH /v1/parties |
identifier (wymagany, przestrzeń wewnętrzna), owner (wymagany, https://gov.pl/nip|<NIP>); treść: Party |
200 zaktualizowana Party |
Filtry kodowane type i status są rozpoznawane po słownikach zadeklarowanych dla zasobu — każda kartoteka ma własny słownik rodzaju, stan strony jest wspólny dla wszystkich instalacji:
| Filtr | Słowniki |
|---|---|
type |
assets · finance · hr |
status |
party-status |
Przestrzeń spoza tych czterech słowników kończy żądanie statusem 400 z nazwą parametru (konwencje §8.1).
Brak tras z {id}; stronę wskazuje się wyłącznie parametrem identifier.
4. Użycie międzymodułowe
- Księgowość: Dostawcy, klienci, odbiorcy płatności, posiadacze kont bankowych
- Kadry: Pracownicy, pracodawcy, kontrahenci
- Magazyn: Operatorzy magazynów, partnerzy logistyczni, odbiorcy towarów
- Majątek: Dysponenci środków trwałych
- CRM: Klienci, kontakty, prospekty sprzedażowe
5. Mapowanie na systemy ERP
| Standard | Odpowiednik Party | Uwagi |
|---|---|---|
| OAGIS | Party, PartyMaster | Identyfikatory (w tym podatkowe), nazwa, lokalizacja, kontakt, rola, klasyfikacja branżowa |
| UBL 2.3 | PartyType | Współdzielony komponent; role przez CustomerParty, SupplierParty itd. |
| GS1 | Party (w kontekście GLN, identyfikacji) | Identyfikacja miejsc, stron; GLN jako identifier |
| ISO 20022 | PartyIdentification, rola (Debtor, Creditor, Agent…) | Rola w komunikacie; Party = podmiot + rola |
| SAP MDG | Business Partner (BP) | BP łączy role (klient, dostawca, kontakt); pojedynczy obiekt, wiele ról |
6. Powiązane zasoby
→ PartyRole — Strona w roli
→ PartyRelationship — Relacja między dwoma PartyRole
→ BankAccount — Rachunki bankowe kontrahenta (w contained)
→ Core Master Data Overview — Wspólne dane główne