Przejdź do treści

Przykłady Party (stron)

Przykłady zasobu Party w jego profilach: Contractor (kontrahent w księgowości), Employee (pracownik), Employer (pracodawca) i AssetHolder (dysponent majątku). Profil niesie meta.profile i jest rozpoznawany po category ze słownika party-kind; zasób wysłany POST-em bez profilu i bez category kończy się 400. Role są w PartyRole, który referuje do Party przez party.

Słowniki: https://api-erp.kamsoft.pl/vs/party-kind, party-status (wspólne) oraz warianty domenowe finance/party-type, finance/party-name, hr/party-type, hr/party-name, assets/party-name, address-component-type, address-type, finance/contact-point-system — Systemy kodowania. contactPoint.system i contactPoint.use to pola tekstowe, nie CodeableConcept.

Legenda placeholderów (zob. konwencje przykładów): urn:oid:2.999.1 — id kontrahenta w księgowości (customer-id), urn:oid:2.999.2 — id pracownika (employee-id), urn:oid:2.999.3 — id organizacji w kadrach (ks-organization-id), urn:oid:2.999.4 — id strony w ewidencji majątku (party-id). Realna postać: urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>.

1. Kontrahent (profil Contractor)

Strona prowadzona w księgowości: identyfikatory (NIP, REGON, id kontrahenta), nazwa jako CodeableConcept, adresy, kontakt, rachunek bankowy jako zasób zagnieżdżony w contained.

{
  "resourceType": "Party",
  "id": "123",
  "meta": {
    "lastModified": "2025-02-20T10:00:00Z",
    "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/Contractor"]
  },
  "category": [
    { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/party-kind", "code": "contractor", "display": "Kontrahent" }] }
  ],
  "type": {
    "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/party-type", "code": "organization", "display": "Podmiot" }]
  },
  "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/party-status", "code": "active", "display": "Aktywny" }] },
  "owner": [
    { "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "9876543210" }, "display": "Firma prowadząca kartotekę" }
  ],
  "identifier": [
    { "system": "urn:oid:2.999.1", "value": "123" },
    { "system": "https://gov.pl/nip", "value": "1234567890" },
    { "system": "https://gov.pl/regon", "value": "123456789" }
  ],
  "name": {
    "coding": [
      { "system": "https://api-erp.kamsoft.pl/vs/finance/party-name", "code": "short-name", "display": "ABC" },
      { "system": "https://api-erp.kamsoft.pl/vs/finance/party-name", "code": "part1-name", "display": "ABC Sp. z o.o." }
    ],
    "text": "ABC Sp. z o.o."
  },
  "address": [
    {
      "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-type", "code": "permanent", "display": "Adres stały" }] },
      "component": [
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "street", "display": "Ulica" }], "text": "Przykładowa" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "building-number", "display": "Numer domu" }], "text": "1" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "flat-number", "display": "Numer lokalu" }], "text": "10" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "locality", "display": "Miejscowość" }], "text": "Warszawa" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "postal-code", "display": "Kod pocztowy" }], "text": "00-001" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "country", "display": "Kraj" }], "text": "PL" }
      ]
    },
    {
      "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-type", "code": "mailing", "display": "Adres do korespondencji" }] },
      "component": [
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "street", "display": "Ulica" }], "text": "Pocztowa" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "building-number", "display": "Numer domu" }], "text": "5" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "locality", "display": "Miejscowość" }], "text": "Warszawa" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "postal-code", "display": "Kod pocztowy" }], "text": "00-002" }
      ]
    }
  ],
  "contactPoint": [
    { "system": "Telefon", "value": "+48 22 123 45 67" },
    { "system": "E-mail", "value": "biuro@abc.pl" }
  ],
  "contained": [
    {
      "resourceType": "BankAccount",
      "accountNumber": "PL61109010140000071219812874",
      "bankName": "Bank Przykładowy",
      "currency": { "text": "PLN" },
      "isDefault": true,
      "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/bank-account-status", "code": "active", "display": "Aktywny" }] }
    }
  ]
}

Uwaga: contactPoint.system to kod tekstowy ze słownika finance/contact-point-system (Telefon, Fax, E-mail, WWW). Słownik address-use nie publikuje kodów, więc address.use pominięto. BankAccount nie ma własnego endpointu — występuje tylko w contained. Role (odbiorca, dostawca) są w PartyRole.

Zapis: POST /v1/parties?owner=https://gov.pl/nip|9876543210 z treścią jak wyżej, bez id i bez value w identyfikatorze wewnętrznym — sama przestrzeń ({ "system": "urn:oid:2.999.1" }) wskazuje instalację rejestrującą stronę (pominięta — rozstrzyga profil), a wartość nadaje księgowość; aktualizacja — PATCH /v1/parties?identifier=urn:oid:2.999.1|123&owner=https://gov.pl/nip|9876543210. Zob. Identyfikacja i parametry wdrożenia §3.

2. Pracownik (profil Employee)

Osoba fizyczna prowadzona w kadrach: nazwa jako CodeableConcept z członami ze słownika hr/party-name, identyfikator wewnętrzny i PESEL, pracodawca jako partOf.

{
  "resourceType": "Party",
  "id": "1001",
  "meta": {
    "lastModified": "2025-02-20T10:00:00Z",
    "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/Employee"]
  },
  "category": [
    { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/party-kind", "code": "employee", "display": "Pracownik" }] }
  ],
  "type": {
    "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/hr/party-type", "code": "person", "display": "Osoba" }]
  },
  "identifier": [
    { "system": "urn:oid:2.999.2", "value": "1001" },
    { "system": "https://gov.pl/pesel", "value": "80010112345" }
  ],
  "name": {
    "coding": [
      { "system": "https://api-erp.kamsoft.pl/vs/hr/party-name", "code": "first-name", "display": "Jan" },
      { "system": "https://api-erp.kamsoft.pl/vs/hr/party-name", "code": "surname", "display": "Kowalski" },
      { "system": "https://api-erp.kamsoft.pl/vs/hr/party-name", "code": "display-name", "display": "Jan Kowalski" }
    ],
    "text": "Jan Kowalski"
  },
  "partOf": {
    "type": "Party",
    "identifier": { "system": "urn:oid:2.999.3", "value": "1" },
    "display": "Szpital Przykładowy"
  },
  "address": [
    {
      "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-type", "code": "permanent", "display": "Adres stały" }] },
      "component": [
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "street", "display": "Ulica" }], "text": "Kwiatowa" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "building-number", "display": "Numer domu" }], "text": "5" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "locality", "display": "Miejscowość" }], "text": "Kraków" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "postal-code", "display": "Kod pocztowy" }], "text": "30-001" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "country", "display": "Kraj" }], "text": "PL" }
      ]
    }
  ],
  "contactPoint": [
    { "system": "Telefon", "value": "+48 500 123 456" },
    { "system": "E-mail", "value": "jan.kowalski@example.com" }
  ]
}

Uwaga: Pracownicy i pracodawcy dzielą jedną przestrzeń identyfikatorów w kadrach (urn:oid:2.999.2 i urn:oid:2.999.3 to w realnej instalacji ta sama przestrzeń), dlatego kluczem referencyjnym jest tylko employee-id. Role (employee, employer) są w PartyRole z party = ten Party; Employment wskazuje pracodawcę i pracownika przez referencje.

3. Pracodawca (profil Employer)

Własna organizacja prowadzona w kadrach.

{
  "resourceType": "Party",
  "id": "1",
  "meta": {
    "lastModified": "2025-02-20T10:00:00Z",
    "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/Employer"]
  },
  "category": [
    { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/party-kind", "code": "employer", "display": "Pracodawca" }] }
  ],
  "type": {
    "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/hr/party-type", "code": "organization", "display": "Podmiot" }]
  },
  "identifier": [
    { "system": "urn:oid:2.999.3", "value": "1" },
    { "system": "https://gov.pl/nip", "value": "9876543210" },
    { "system": "https://gov.pl/regon", "value": "987654321" }
  ],
  "name": {
    "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/hr/party-name", "code": "display-name", "display": "Szpital Przykładowy" }],
    "text": "Szpital Przykładowy"
  },
  "address": [
    {
      "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-type", "code": "permanent", "display": "Adres stały" }] },
      "component": [
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "street", "display": "Ulica" }], "text": "Marszałkowska" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "building-number", "display": "Numer domu" }], "text": "1" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "locality", "display": "Miejscowość" }], "text": "Warszawa" },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/address-component-type", "code": "postal-code", "display": "Kod pocztowy" }], "text": "00-001" }
      ]
    }
  ],
  "contactPoint": [
    { "system": "Telefon", "value": "+48 22 999 00 00" }
  ]
}

Uwaga: Oddziały i placówki nie są osobnym rodzajem strony — hierarchię organizacji wyraża partOf (strona nadrzędna), a jednostki organizacyjne to OrganizationUnit. Miejsca fizyczne (magazyn, miejsce użytkowania) to Location.

4. Dysponent majątku (profil AssetHolder)

Osoba odpowiedzialna za środki trwałe, prowadzona w ewidencji majątku.

{
  "resourceType": "Party",
  "id": "77",
  "meta": {
    "lastModified": "2025-02-20T10:00:00Z",
    "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/AssetHolder"]
  },
  "category": [
    { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/party-kind", "code": "asset-holder", "display": "Dysponent majątku" }] }
  ],
  "type": {
    "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/party-type", "code": "person", "display": "Osoba" }]
  },
  "identifier": [
    { "system": "urn:oid:2.999.4", "value": "77" }
  ],
  "name": {
    "coding": [
      { "system": "https://api-erp.kamsoft.pl/vs/assets/party-name", "code": "first-name", "display": "Anna" },
      { "system": "https://api-erp.kamsoft.pl/vs/assets/party-name", "code": "last-name", "display": "Nowak" }
    ],
    "text": "Anna Nowak"
  },
  "attribute": [
    {
      "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/assets/party-attribute-type", "code": "fkw-number" }] },
      "value": { "valueString": "K-000123" }
    }
  ]
}

Uwaga: Dysponent występuje w FixedAssetAllocation w wymiarze responsible-party. Atrybut fkw-number wiąże go z kartoteką kontrahenta w księgowości.

5. Diagramy zależności obiektów Party

5.1. Profile Party (category z party-kind)

flowchart TB
    subgraph Party["Zasób Party"]
        direction TB
        CON[Contractor\ncategory: contractor\nksięgowość — NIP, REGON, adresy, rachunek]
        EMP[Employee\ncategory: employee\nkadry — imię, nazwisko, PESEL, partOf]
        EMR[Employer\ncategory: employer\nkadry — własna organizacja]
        AH[AssetHolder\ncategory: asset-holder\nmajątek — osoba odpowiedzialna]
    end

5.2. Party i powiązania (PartyRole, DocumentReference)

erDiagram
    PartyRole }o--|| Party : "party"
    Party ||--o{ DocumentReference : "participant"
    Party }o--o| Party : "partOf"
    PartyRelationship }o--|| PartyRole : "partyFrom"
    PartyRelationship }o--|| PartyRole : "partyTo"

    Party {
        string id
        CodeableConcept category
        CodeableConcept type
        CodeableConcept name
        Address address
        ContactPoint contactPoint
        Reference partOf
    }

    PartyRole {
        Reference party
        CodeableConcept role
    }

    DocumentReference {
        Reference participant
    }

5.3. Użycie Party w różnych obszarach

flowchart LR
    P[Party]
    P --> FIN[Księgowość: PostingInstruction.participant\nseller, buyer, recipient]
    P --> WHS[Magazyn: InventoryDocument, PurchaseOrder\ndostawca, odbiorca]
    P --> HR[Kadry: Employment, PartyRole\nemployer, employee]
    P --> AST[Majątek: FixedAssetAllocation\nresponsible-party]

Podsumowanie: czym może być Party

Profil category (party-kind) type (party-type) Opis
Contractor contractor finance: organization Kontrahent w księgowości – NIP, REGON, adresy, rachunki w contained; role customer/supplier w PartyRole
Employee employee hr: person Pracownik – imię i nazwisko jako człony hr/party-name, PESEL, pracodawca w partOf
Employer employer hr: organization Własna organizacja prowadząca kadry
AssetHolder asset-holder assets: person, organization Osoba lub podmiot odpowiedzialny za środki trwałe

Wszystkie profile używają tej samej struktury Party: identifier, name, address, contactPoint, partOf; category rozróżnia profil, a type rodzaj podmiotu w danym obszarze. Party nie zawiera partyRole – to PartyRole referuje do Party przez party. Mapowanie z SAP Business Partner, Oracle TCA Party, UBL PartyType, OAGIS Party na identifier, Address, ContactPoint jest spójne.