Przejdź do treści

Systemy kodowania i value sety

W Implementation Guide wszystkie pola typu CodeableConcept oraz typ identyfikatora w Identifier używają systemów kodowania w przestrzeni nazw platformy: https://api-erp.kamsoft.pl/ns/. Poniżej zestawienie systemów i przykładowych wartości (value sety) występujących w modelach i przykładach.

Code system a value set:
Code system (system kodowania) określa przestrzeń nazw (URL) i pełny zestaw kodów z definicjami (np. document-type, document-position-type). Value set (zbiór wartości) doprecyzowuje ten system w danym kontekście: wybiera dopuszczalne kody dla konkretnego pola, zasobu lub profilu (np. „typy dokumentu dozwolone w FK”, „typy pozycji na fakturze”). Dzięki value setom można jawnie określić, które kody z systemu są dozwolone w API lub w walidacji (np. Document.type w profilu FK tylko z value setu DocumentType-FK). W poniższych sekcjach: §1 — code systemy, §2 — przykładowe kody w systemach, §2a — value sety kontekstowe doprecyzowujące systemy.


1. Systemy kodowania (Code Systems)

Każdy system ma adres URL w formie https://api-erp.kamsoft.pl/ns/<nazwa-systemu>.

System Użycie Zasoby / kontekst
address-line-type Typ elementu linii adresu (street, building-number, apartment-number, entrance, floor, district) Address.line
address-type Typ adresu (physical) Address
address-use Zastosowanie adresu (work, billing, home) Address
allocation-item-category Kategoria pozycji alokacji kosztów — klasyfikuje pozycje w schemacie podziału kosztów (np. bezpośrednia, pośrednia). AllocationItem
allocation-item-code Kod pozycji alokacji kosztów — identyfikuje konkretny element w schemacie podziału kosztów pomiędzy jednostki organizacyjne lub projekty. AllocationItem
allocation-item-type Typ pozycji alokacji kosztów — określa charakter pozycji w kluczu podziału kosztów (np. procentowy, ilościowy, stały). AllocationItem
asset-component-attribute-type Typ atrybutu komponentu majątku — klasyfikuje dodatkowe atrybuty komponentu majątku (np. tekstowy, liczbowy, datowy). AssetComponent
asset-component-category Kategoria komponentu majątku — grupuje komponenty majątku według kategorii ewidencyjnej. AssetComponent
asset-component-type Typ komponentu majątku — klasyfikuje komponenty majątku według rodzaju (np. część składowa, ulepszenie, doposażenie). AssetComponent
bank-account-category Kategoria rachunku bankowego — grupuje rachunki bankowe według kategorii biznesowej (np. operacyjny, inwestycyjny). BankAccount
bank-account-currency Waluta rachunku bankowego — określa dopuszczalne kody walut dla rachunków bankowych kontrahenta lub firmy (np. PLN, EUR, USD). BankAccount
bank-account-status Status rachunku bankowego — określa bieżący stan rachunku bankowego (np. aktywny, zablokowany, zamknięty). BankAccount
bank-account-type Typ rachunku bankowego — klasyfikuje rachunki bankowe według przeznaczenia (np. bieżący, pomocniczy, walutowy). BankAccount
capability-type Typ / kategoria zdolności (Capability.type, category) Capability
contact-point-system Typ kontaktu (phone, email) ContactPoint
cost-assignment-position-category Kategoria pozycji przypisania kosztu — grupuje pozycje przypisania kosztów według kategorii (np. bezpośrednia, pośrednia). CostAssignmentPosition
cost-assignment-position-type Typ pozycji alokacji kosztów (invoice-cost, material-cost, labor-cost, overhead-cost, allocation) CostAssignment.position
cost-carrier-attribute-type Typ atrybutu nośnika kosztów — klasyfikuje dodatkowe atrybuty nośnika kosztów (np. tekstowy, liczbowy, datowy). CostCarrier
cost-carrier-category Kategoria nośnika kosztów — grupuje nośniki kosztów według kategorii (np. produkcyjny, usługowy, administracyjny). CostCarrier
cost-carrier-type Typ nośnika kosztów (project, internal-order, cost-center, product, service) CostCarrier
document-attribute-type Rodzaj atrybutu dokumentu (Attribute.code w Document.attribute) Document
document-category Kategoria dokumentu — grupuje dokumenty według kategorii biznesowej (np. sprzedażowy, zakupowy, wewnętrzny). Document
document-position-category Kategoria pozycji dokumentu — grupuje pozycje dokumentu według kategorii biznesowej. DocumentPosition
document-position-code Kod pozycji dokumentu — identyfikuje rodzaj pozycji w ramach dokumentu (np. konkretna usługa, towar, składnik). DocumentPosition
document-position-status Status pozycji dokumentu — określa stan realizacji pojedynczej pozycji (np. otwarta, zrealizowana, anulowana). DocumentPosition
document-position-type Rodzaj pozycji (DocumentPosition.code) DocumentPosition
document-position-value Typ wartości pozycji dokumentu — określa rodzaj kwoty przypisanej do pozycji (np. netto, brutto, podatek, rabat). DocumentPosition
document-space Przestrzeń dokumentu — wskazuje do jakiej domeny w systemie należy dokument (np. HR Inbox — skrzynka dokumentów kadrowych). Document
document-status Status dokumentu (Document.status) Document
document-type Typ dokumentu (Document.type) Document
employee-professional-group-attribute-type Typ atrybutu grupy zawodowej pracownika — klasyfikuje dodatkowe atrybuty grupy zawodowej pracownika. EmployeeProfessionalGroup
employee-professional-group-category Kategoria grupy zawodowej pracownika — grupuje grupy zawodowe pracowników według kategorii kadrowej. EmployeeProfessionalGroup
employee-professional-group-type Typ grupy zawodowej pracownika — klasyfikuje grupy zawodowe pracownika według rodzaju. EmployeeProfessionalGroup
employment-category Kategoria zatrudnienia — grupuje zatrudnienia według kategorii kadrowej (np. pracownik, współpracownik, stażysta). Employment
employment-kind Rodzaj umowy (indefinite, fixed-term, contract-zlecenie, contract-dzielo…) Employment.kind
employment-type Typ zatrudnienia (employment-contract) Employment
fixed-asset-allocation-atribute-type Wymiar alokacji środka trwałego — kryterium przypisania środka trwałego do miejsc powstawania kosztów (np. dział, lokalizacja). FixedAssetAllocation
fixed-asset-allocation-category Kategoria alokacji środka trwałego — grupuje alokacje środków trwałych według kategorii (np. organizacyjna, projektowa). FixedAssetAllocation
fixed-asset-allocation-dimension Wymiar przypisania srodka (location, cost-center, responsible-party) FixedAssetAllocation
fixed-asset-allocation-dimension Typ atrybutu wymiaru alokacji środka trwałego — klasyfikuje dodatkowe atrybuty wymiaru alokacji środka trwałego. FixedAssetAllocation
fixed-asset-allocation-type Typ alokacji środka trwałego — określa rodzaj przypisania środka trwałego do obiektów kosztowych (np. procentowy, kwotowy). FixedAssetAllocation
fixed-asset-attribute-type Typ atrybutu kartoteki środka trwałego — klasyfikuje dodatkowe atrybuty w kartotece środka trwałego (np. tekstowy, liczbowy, datowy). FixedAsset
fixed-asset-category Kategoria środka trwałego — grupuje środki trwałe według kategorii ewidencyjnej (np. nieruchomości, urządzenia techniczne). FixedAsset
fixed-asset-deprecation-type-balance Metoda amortyzacji bilansowej środka trwałego — określa sposób naliczania odpisów amortyzacyjnych dla celów bilansowych (np. liniowa, degresywna). FixedAsset
fixed-asset-deprecation-type-tax Metoda amortyzacji podatkowej środka trwałego — określa sposób naliczania odpisów amortyzacyjnych dla celów podatku CIT (np. liniowa, jednorazowa). FixedAsset
fixed-asset-document-attribute-type Typ atrybutu dokumentu środka trwałego — klasyfikuje dodatkowe atrybuty dokumentu w module środków trwałych. FixedAssetDocument
fixed-asset-document-position-category Kategoria pozycji dokumentu środka trwałego — grupuje pozycje dokumentów ŚT według kategorii. FixedAssetDocumentPosition
fixed-asset-document-position-type Typ pozycji dokumentu środka trwałego — określa rodzaj pozycji na dokumencie ŚT (np. przyjęcie, likwidacja, przeszacowanie). FixedAssetDocumentPosition
fixed-asset-document-position-value Typ wartości pozycji dokumentu środka trwałego — określa rodzaj kwoty na pozycji dokumentu ŚT (np. wartość nabycia, wartość umorzenia, wartość netto). FixedAssetDocumentPosition
fixed-asset-document-status Status wewnetrzny dokumentu ESM (open, closed, posted) FixedAssetDocument
fixed-asset-document-symbol Symbol dokumentu środka trwałego — skrót oznaczający rodzaj dokumentu w module ŚT (np. OT — przyjęcie, LT — likwidacja, MT — przesunięcie). FixedAssetDocument
fixed-asset-document-type Typ dokumentu ESM (purchase, sale, liquidation, acceptance, production, write-off, location-change, value-change, responsible-change, investment-protocol) FixedAssetDocument
fixed-asset-status Status srodka trwalego (investment, accepted, depreciated, liquidated, sold) FixedAsset
fixed-asset-type Rodzaj majatku (fixed-asset, equipment, wnip) FixedAsset
grant-assignment-basis Podstawa przypisania dotacji/dofinansowania — określa na jakiej podstawie przyznano dotację (np. umowa, decyzja administracyjna, projekt unijny). GrantAssignment
grant-assignment-category Kategoria przypisania dotacji/dofinansowania — grupuje przypisania dotacji według kategorii (np. unijne, krajowe, samorządowe). GrantAssignment
grant-assignment-type Typ przypisania dotacji/dofinansowania — klasyfikuje rodzaje przypisań dotacji do obiektów (np. projektowe, operacyjne). GrantAssignment
inventory-document-attribute-status Status dokumentu magazynowego — określa bieżący stan dokumentu magazynowego (np. szkic, zatwierdzony, zrealizowany). InventoryDocument
inventory-document-attribute-type Typ atrybutu dokumentu magazynowego — klasyfikuje dodatkowe atrybuty dokumentu magazynowego (np. tekstowy, liczbowy, datowy). InventoryDocument
inventory-document-attribute-type Typ atrybutu pozycji dokumentu magazynowego — klasyfikuje dodatkowe atrybuty pozycji dokumentu magazynowego. InventoryDocumentPosition
inventory-document-movement-category Kategoria ruchu magazynowego — grupuje ruchy magazynowe według kategorii (np. przyjęcie, wydanie, przesunięcie). InventoryDocument
inventory-document-movement-type Typ ruchu magazynowego — określa rodzaj operacji magazynowej na dokumencie (np. PZ, WZ, MM, inwentaryzacja). InventoryDocument
inventory-document-position-status Status pozycji dokumentu magazynowego — określa stan realizacji pozycji (np. otwarta, częściowo zrealizowana, zamknięta, anulowana). InventoryDocumentPosition
inventory-movement-type Typ ruchu magazynowego (receipt, issue, transfer, adjustment) InventoryDocument
invoice-category Kategoria metody płatności — grupuje metody płatności według kategorii biznesowej (np. standardowa, preferencyjna). Invoice
invoice-payment-method Metoda płatności faktury — określa sposób zapłaty za fakturę (np. przelew, gotówka, karta, kompensata). Invoice
invoice-position-category Kategoria pozycji faktury — grupuje pozycje fakturowe według kategorii biznesowej. InvoicePosition
invoice-position-discount Typ rabatu na pozycji faktury — określa rodzaj udzielonego upustu na pozycji (np. procentowy, kwotowy). InvoicePosition
invoice-position-excise-type Typ akcyzy na pozycji faktury — identyfikuje kategorię wyrobu akcyzowego dla celów podatkowych (np. alkohol, paliwo, wyroby tytoniowe). InvoicePosition
invoice-position-type Typ pozycji faktury — określa rodzaj pozycji na fakturze (np. towar, usługa, opłata dodatkowa). InvoicePosition
invoice-position-vat-rate Stawka VAT na pozycji faktury — określa stawkę podatku VAT na pozycji faktury sprzedaży/zakupu (np. 23%, 8%, 5%, 0%, ZW, NP). InvoicePosition
invoice-type Typ metody płatności — klasyfikuje metody płatności według rodzaju (np. gotówkowa, bezgotówkowa, kompensata). Invoice
location-attribute-type Rodzaj atrybutu lokalizacji (Attribute.code w Location.attribute) Location
location-category Kategoria lokalizacji — grupuje lokalizacje według kategorii biznesowej (np. wewnętrzna, zewnętrzna). Location
location-status Status lokalizacji — określa bieżący stan lokalizacji (np. aktywna, nieaktywna, w budowie). Location
location-type Typ lokalizacji (storage, warehouse) Location
organization-assignment-attribute-type Typ atrybutu przypisania do jednostki organizacyjnej — klasyfikuje dodatkowe atrybuty przypisania organizacyjnego. OrganizationAssignment
organization-assignment-category Kategoria przypisania do jednostki organizacyjnej — grupuje przypisania organizacyjne według kategorii. OrganizationAssignment
organization-assignment-hierarchy-level Stopień hierarchii (primary-manager, deputy) OrganizationAssignment
organization-assignment-type Typ przypisania do jednostki organizacyjnej — określa rodzaj powiązania z jednostką organizacyjną (np. główne, tymczasowe, zastępstwo). OrganizationAssignment
organization-unit-attribute-type Rodzaj atrybutu jednostki (np. MPK – ośrodek kosztów) OrganizationUnit.attribute
organization-unit-category Kategoria jednostki organizacyjnej — grupuje jednostki organizacyjne według kategorii (np. produkcyjna, administracyjna). OrganizationUnit
organization-unit-status Status jednostki organizacyjnej — określa bieżący stan jednostki organizacyjnej (np. aktywna, nieaktywna, zlikwidowana). OrganizationUnit
organization-unit-type Typ jednostki organizacyjnej (department, branch) OrganizationUnit
party-attribute-type Rodzaj atrybutu strony (registered, registration-date, external-id-rcp, barcode) Party.attribute
party-category Kategoria strony (np. warehouse) Party
party-name Typ nazwy strony (official, short, trade, legal, former) Party.name
party-relationship-type Typ relacji — klasyfikuje relacje między podmiotami w systemie (np. podległość, partnerstwo, powiązanie kapitałowe). PartyRelationship
party-role Rola podmiotu w systemie — określa w jakiej relacji kontrahent występuje wobec firmy (np. dostawca, odbiorca, pracownik, bank, instytucja publiczna). PartyRole
party-role-category Kategoria uczestnika — grupuje uczestników według kategorii (np. wewnętrzny, zewnętrzny). PartyRole
party-role-status Status uczestnika — określa bieżący stan uczestnika (np. aktywny, nieaktywny, zawieszony). PartyRole
party-role-type Typ uczestnika — klasyfikuje uczestników według ich roli w procesie (np. główny, pomocniczy, obserwator). PartyRole
party-status Status strony — określa bieżący stan podmiotu w systemie (np. aktywny, zablokowany, archiwalny). Party
party-type Typ strony (Party: organization, person, branch) Party
payment-aml-check-status Status weryfikacji AML płatności — określa wynik kontroli pod kątem przepisów o przeciwdziałaniu praniu pieniędzy (np. zweryfikowana, w toku, flaga ryzyka). Payment
payment-attribute-type Typ atrybutu płatności — klasyfikuje dodatkowe atrybuty płatności (np. tekstowy, liczbowy, datowy). Payment
payment-category Kategoria płatności — grupuje płatności według kategorii biznesowej (np. operacyjna, inwestycyjna). Payment
payment-payment-method Metoda realizacji płatności — określa sposób wykonania płatności w module rozrachunków FK (np. przelew bankowy, polecenie zapłaty, kompensata, gotówka). Payment
payment-reconciliation-status Status uzgodnienia płatności — określa stan rozliczenia płatności z dokumentem (np. nieuzgodniona, częściowo uzgodniona, w pełni rozliczona). Payment
payment-type Typ płatności — klasyfikuje płatności według rodzaju (np. przychodzące, wychodzące, wewnętrzne). Payment
product-definition-attribute-type Typ atrybutu definicji produktu — klasyfikuje dodatkowe atrybuty definicji produktu (np. tekstowy, liczbowy, datowy). ProductDefinition
product-definition-category Kategoria definicji produktu — grupuje definicje produktów według kategorii (np. handlowa, produkcyjna). ProductDefinition
product-definition-status Status definicji produktu — określa bieżący stan definicji produktu (np. aktywny, wycofany, w przygotowaniu). ProductDefinition
product-definition-type Typ definicji produktu — klasyfikuje definicje produktów według rodzaju (np. towar, usługa, zestaw). ProductDefinition
professional-group-attribute-type Typ atrybutu grupy zawodowej — klasyfikuje dodatkowe atrybuty grupy zawodowej (np. tekstowy, liczbowy, datowy). ProfessionalGroup
professional-group-category Kategoria grupy zawodowej — grupuje grupy zawodowe według kategorii kadrowej. ProfessionalGroup
professional-group-status Status grupy zawodowej — określa bieżący stan grupy zawodowej (np. aktywna, nieaktywna, archiwalna). ProfessionalGroup
professional-group-type Typ grupy zawodowej — klasyfikuje grupy zawodowe według rodzaju (np. stanowiskowa, kompetencyjna, płacowa). ProfessionalGroup
purchase-order-attribute-type Typ atrybutu zamówienia zakupu — klasyfikuje dodatkowe atrybuty zamówienia zakupu (np. tekstowy, liczbowy, datowy). PurchaseOrder
purchase-order-category Kategoria zamówienia zakupu — grupuje zamówienia zakupu według kategorii biznesowej (np. materiałowe, usługowe). PurchaseOrder
purchase-order-payment-terms Warunki płatności zamówienia zakupu — określa terminy zapłaty stosowane przy zamówieniach od dostawców (np. 14 dni netto, 30 dni netto, płatność z góry). PurchaseOrder
purchase-order-position-status Status pozycji zamówienia zakupu — określa etap realizacji pozycji zamówienia (np. szkic, wysłane, częściowo zrealizowane, zamknięte, anulowane). PurchaseOrderPosition
purchase-order-status Status zamówienia zakupu — określa bieżący stan zamówienia zakupu (np. szkic, wysłane, potwierdzone, zamknięte). PurchaseOrder
purchase-order-type Typ zamówienia zakupu — klasyfikuje zamówienia zakupu według rodzaju (np. standardowe, ramowe, awaryjne). PurchaseOrder
value-item-quantity-type Typ wartości w valueItem (np. ilość, cena, netto, VAT) DocumentPosition
value-item-type Typ pozycji wartości — określa rodzaj składnika wartości w modelu finansowym (np. kwota netto, VAT, brutto, prowizja). ValueItem
value-item-value Wartość pozycji wartości — dopuszczalne kody dla danego elementu wartościowego uzupełniające słownik typów pozycji wartości. ValueItem
vat-rate Stawka VAT (code w valueCodeableConcept) DocumentPosition

Identyfikatory: Znaczenie identyfikatora wynika z Identifier.system (URI). Oprócz urn:pl:nip, urn:pl:regon używane są systemy domenowe HR w przestrzeni https://api-erp.kamsoft.pl/ns/: 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. Identyfikatory urzędowe: https://gov.pl/pesel, https://gov.pl/nip. Opcjonalnie Identifier.type (CodeableConcept) może opisywać rodzaj w formie tekstu (display).


2. Value sety (przykładowe kody)

Wartości code używane w przykładach i opisach dla poszczególnych systemów.

document-type

Code Opis
sales-order Zamówienie sprzedaży
invoice Faktura
goods-receipt Przyjęcie towaru (PZ)
training-record Dokumentacja szkolenia
workflow-approval Zatwierdzenie w obiegu
decree Dekret księgowy

document-status

Code Opis
issued Wystawione
completed Zrealizowane
approved Zatwierdzony

inventory-movement-type

Używany w InventoryDocument.movementType. Odpowiednik PZ/WZ/przesunięcia jako jeden zasób zorientowany na zmianę (ilość, lokalizacja, własność).

Code Opis Mapowanie
receipt Przyjęcie towaru PZ
issue Wydanie towaru WZ
transfer Przesunięcie między lokalizacjami Przesunięcie
adjustment Korekta stanu Korekta inwentaryzacyjna

fixed-asset-allocation-dimension

Używany w FixedAssetAllocation.dimension.

Code Opis Mapowanie
location Lokalizacja Miejsce użytkowania
cost-center Ośrodek kosztów MPK / CKS
responsible-party Osoba odpowiedzialna Kontrahent / pracownik
responsible-party Osoba odpowiedzialna Kontrahent / pracownik

fixed-asset-status

Używany w FixedAsset.status.

Code Opis Mapowanie
investment Inwestycja W
accepted Przyjęty P
depreciated Zamortyzowany Z
liquidated Zlikwidowany L
sold Sprzedany S

fixed-asset-type

Używany w FixedAsset.type.

Code Opis Mapowanie
fixed-asset Środek trwały S
equipment Wyposażenie W
wnip Wartość niematerialna i prawna P

fixed-asset-document-type

Używany w FixedAssetDocument.type.

Code Opis Mapowanie
purchase Zakup ZK
sale Sprzedaż SP
liquidation Likwidacja LT
acceptance Przyjęcie OT
production Wytworzenie WT
write-off Odpis OD
location-change Zmiana miejsca ZM
value-change Zmiana wartości ZW
responsible-change Zmiana osoby odpowiedzialnej ZO
investment-protocol Protokół inwestycji PI

fixed-asset-document-status

Używany w FixedAssetDocument.status.

Code Opis Mapowanie
open Otwarty O
closed Zamknięty Z
posted Zaksięgowany K

document-position-type

Code Opis
order-line Pozycja zamówienia
invoice-line Wiersz faktury
vat-summary-line Podsumowanie VAT
goods-receipt-line Pozycja PZ
decree-line Wiersz dekretu

document-attribute-type

Code Opis
total-net Suma netto
total-vat Suma VAT
total-excise Suma akcyzy (dokument)
total-gross Suma brutto

value-item-quantity-type

Code Opis
quantity Ilość
unit-price Cena jedn.
net-amount Kwota netto
vat-amount Kwota VAT
excise-amount Kwota akcyzy (wiersz)

invoice-position-excise-type

Code Opis (przykład)
(kody zależne od ustawy o podatku akcyzowym) Rodzaj wyrobu akcyzowego (np. alkohol, tytoń, paliwa) – wartość w InvoicePosition.exciseType / valueCodeableConcept

vat-rate

Code Opis (przykład)
23 23% (stawka podstawowa)
8 8% (obniżona)
5 5% (obniżona)
0 0% (obniżona / eksport itd.)
A, B, C, D, E kody literowe z rozporządzenia MF (kasy fiskalne) – patrz §4 Oficjalne słowniki

Źródło oficjalne: Matryca stawek VAT (podatki.gov.pl), rozporządzenie MF z 29.04.2019 r. (Dz.U. poz. 816).

party-type

Code Opis
organization Organizacja
person Osoba
branch Oddział

party-category

Code Opis
warehouse Magazyn

party-name

Code Opis
official Nazwa oficjalna
short Nazwa skrócona
trade Nazwa handlowa
legal Nazwa prawna / rejestrowa
former Nazwa historyczna

address-use

Code Opis
work Siedziba / służbowy
billing Rozliczeniowy
home Prywatny

address-line-type

Code Opis
street Ulica
building-number Numer budynku
apartment-number Numer lokalu
entrance Klatka / wejście
floor Piętro
district Dzielnica / osiedle

address-type

Code Opis
physical Fizyczny

contact-point-system

Code Opis
phone Telefon
email E-mail

location-type

Code Opis
storage Składowanie
warehouse Magazyn (węzeł hierarchii)

location-attribute-type

Code Opis
area Powierzchnia (valueQuantity)
temperature Temperatura / warunki (valueQuantity lub valueCodeableConcept)
zone-type Typ strefy (valueCodeableConcept)

cost-carrier-type

Code Opis
project Projekt
internal-order Zlecenie wewnętrzne
cost-center Centrum kosztów / MPK
product Produkt
service Usługa

cost-assignment-position-type

Code Opis
invoice-cost Koszt z faktury
material-cost Koszt materiałowy
labor-cost Koszt pracy / wynagrodzeń
overhead-cost Koszt pośredni
allocation Alokacja / przesunięcie międzyokresowe

employment-type

Code Opis
employment-contract Umowa o pracę
contract-of-mandate Umowa zlecenie

employment-kind

Używany w Employment.kind (rodzaj umowy).

Code Opis
indefinite Na czas nieokreślony
fixed-term Na czas określony
contract-zlecenie Umowa zlecenie
contract-dzielo Umowa o dzieło

party-attribute-type

Używany w Party.attribute (cechy rozszerzające, np. ewidencja pracownika).

Code Opis
registered Czy ewidencjonowany
registration-date Data rozpoczęcia ewidencji
external-id-rcp Identyfikator w systemie RCP (time-and-attendance)
barcode Kod kreskowy (gdy jako atrybut)

specialty-level

Używany w EmployeeSpecialty.level (stopień specjalizacji).

Code Opis (przykład)
I I stopień
II II stopień

organization-unit-type

Code Opis
board Zarząd
department Wydział
branch Oddział
plant Zakład (wewnątrz wydziału)
section Sekcja (wewnątrz zakładu)
unit Komórka organizacyjna
pion Pion (jednostka organizacyjna w strukturze, jak dział)

organization-unit-attribute-type

Code Opis
cost-center Ośrodek kosztów (MPK)

organization-assignment-hierarchy-level

Code Opis
primary-manager Główny przełożony (kierownik)
deputy Zastępca
main-director Dyrektor główny (wydział)
technical-director Dyrektor techniczny (wydział)

capability-type

Code Opis
access Dostęp (odczyt, przeglądanie)
approval Zatwierdzanie (akceptacja, workflow)
admin Administracja (konfiguracja, zarządzanie)
execute Wykonanie (operacja, akcja)

2a. Value sety kontekstowe (doprecyzowanie systemów)

Value sety odwołują się do code systemów i zawężają dopuszczalne kody do danego kontekstu (zasób, profil, endpoint). Ułatwia to walidację i dokumentację API: zamiast „dowolny kod z document-type” określamy np. „tylko kody z value setu DocumentType-FK”.

Value set (nazwa / identyfikator) Code system Kontekst Dopuszczalne kody (zawężenie)
DocumentType-FK document-type Document w profilu FK (faktura) invoice, correction, proforma, … — typy dokumentów księgowych/faktur
DocumentType-HR document-type Document w kontekście HR training-record, employment-document, …
DocumentType-WHS document-type Document w kontekście WMS (zapotrzebowania i powiązania międzydomenowe) goods-receipt, goods-issue, transfer, …
DocumentAttributeType-Summary document-attribute-type Document.attribute (podsumowanie) total-net, total-vat, total-excise, total-gross (oraz ewent. total-net-23, total-vat-23 itd.)
DocumentPositionType-Decree document-position-type DocumentPosition w dekrecie decree-line
DocumentPositionType-Invoice document-position-type DocumentPosition w fakturze invoice-line, vat-summary-line
DocumentPositionType-Order document-position-type DocumentPosition w zamówieniu order-line
QuantityItemType-InvoiceLine value-item-quantity-type DocumentPosition (invoice-line) quantity, unit-price, net-amount, vat-amount, excise-amount, discount
AssetKind asset-kind ESM (FixedAsset, AssetComponent) słownik rodzajów majątku
ESMAttribute esm-attribute ESM (FixedAsset, AssetComponent, FixedAssetDocument) słownik cech w obszarze środków trwałych
ESMDocumentType esm-document-type ESM (FixedAssetDocument) słownik typów dokumentów w obszarze środków trwałych
DepreciationType allocation-dimension FixedAsset.depreciationTypeBalance, FixedAsset.depreciationTypeTax linear, linear-accelerated, linear-decelerated, declining, one-time, none
FixedAssetStatus fixed-asset-status FixedAsset.status investment, accepted, depreciated, liquidated, sold
FixedAssetType fixed-asset-type FixedAsset.type fixed-asset, equipment, wnip
AllocationDimension fixed-asset-allocation-dimension FixedAssetAllocation.dimension location, cost-center, responsible-party, funding-source
FixedAssetDocumentStatus fixed-asset-document-status FixedAssetDocument.status open, closed, posted
FixedAssetDocumentType fixed-asset-document-type FixedAssetDocument.type purchase, sale, liquidation, acceptance, production, write-off, location-change, value-change, responsible-change, investment-protocol
HRInboxDocumentType hr-inbox-document-type HR (Document, document-space=hr-inbox) słownik typów dokumentów w obszarze HR
Specialty specialty HR (EmployeeSpecialty, Qualification) słownik specjalizacji w obszarze HR
InventoryMovementType inventory-movement-type InventoryDocument.movementType receipt (PZ), issue (WZ), transfer, adjustment
PartyType party-type Party organization, person, branch
VatRate-PL vat-rate Stawka VAT (wiersz faktury, podsumowanie) 23, 8, 5, 0 oraz opcjonalnie A–G (kody fiskalne) — zob. §4.2
UnitOfMeasure unit-of-measure WMS/FK/ESM (quantity, valueItem.quantity.unit) słownik jednostek miary

Uwaga: Powyższe value sety są kontekstowym doprecyzowaniem code systemów. W API lub schematach (OpenAPI/JSON Schema) można powiązać pole z konkretnym value setem (np. Document.type w profilu FK z DocumentType-FK), co jednoznacznie określa dozwolone wartości. Pełna lista kodów dla każdego value setu wynika z §2 (przykładowe kody w systemach) oraz z wymagań biznesowych profilu.


3. Powiązanie z modelami

Dopuszczalne wartości w polach CodeableConcept/Identifier w poszczególnych zasobach można zawęzić do value setów kontekstowych (zob. §2a).

  • Document, DocumentPosition, Document.attribute → document-type, document-status, document-position-type, document-attribute-type, value-item-quantity-type, vat-rate, invoice-position-excise-type. Identyfikatory dokumentu: Identifier.system (np. origin, eod) + value.
  • Party → party-type, party-category, party-name, address-use, address-line-type, address-type, contact-point-system. Identyfikatory strony: Identifier.system (urn:pl:nip, urn:pl:regon itd.) + value.
  • Location → location-type, location-attribute-type, status; owner, managingParty (Reference Party – firma, organizacja, osoba, jednostka organizacyjna). Identyfikatory: Identifier.system + value.
  • WMS (InventoryDocument) → inventory-movement-type (receipt, issue, transfer, adjustment), status. Identyfikatory: Identifier.system + value (numer PZ/WZ/MM).
  • ESM (FixedAsset, AssetComponent, FixedAssetAllocation, FixedAssetDocument) → fixed-asset-status, fixed-asset-type, allocation-dimension, fixed-asset-allocation-dimension, fixed-asset-document-type, fixed-asset-document-status. Reuse: Location jako usage-place, PartyRole jako responsible-party, Document jako funding-agreement. Identyfikatory: Identifier.system (np. barcode) + value.
  • FK – Księgowanie (warianty i alokacje kosztów) — zasoby w Resources/FK/Accounting → status, document-type, document-position-type. Identyfikatory: Identifier.system + value.
  • HR (Employment, Position, OrganizationUnit, OrganizationAssignment, Qualification, ProfessionalGroup, EmployeeProfessionalGroup, Capability, GrantAssignment) → employment-type, employment-kind, work-time-unit; Party → name (CodeableConcept; system party-name), attribute (party-attribute-type), employer; OrganizationUnit → organization (1..1), symbol, shortName, address, organization-unit-type, organization-unit-attribute-type (np. cost-center/MPK); OrganizationAssignment → organization-assignment-hierarchy-level, hierarchyIndex, hierarchyLabel; Capability, GrantAssignment → capability-type; GrantAssignment → assignedTo (Party/PartyRole/Position/OrganizationUnit), scope, granted (Reference Capability), period, basis, basedOn. Identyfikatory HR: hr-employee-id, hr-employer-id, hr-position-id, hr-organization-unit-id, hr-employment-id, hr-professional-group-id, integration-id, time-and-attendance-id, barcode (Identifier.system + value).

W razie rozszerzania modelu nowe kody dodaje się do odpowiedniego systemu (lub definiuje nowy system w przestrzeni https://api-erp.kamsoft.pl/ns/).


4. Oficjalne i zewnętrzne słowniki kodowania

Dla identyfikatorów państwowych i stawek podatkowych warto używać oficjalnych źródeł i – tam gdzie istnieją – oficjalnych lub powszechnie przyjętych systemów (URI). Poniżej zestawienie dla Polski.

4.1 Identyfikatory podmiotów (NIP, REGON, KRS)

Identyfikator Opis Oficjalny rejestr / źródło Rekomendowany Identifier.system (URI) Uwagi
NIP Numer Identyfikacji Podatkowej (10 cyfr, ostatnia kontrolna) Ministerstwo Finansów (Biała lista VAT), GUS (wyszukiwarka REGON po NIP) urn:pl:nip org-id.guide: schemat PL-NIP-&lt;numer&gt;. Weryfikacja: wyszukiwarkaregon.stat.gov.pl, API Wykazu podatników VAT (gov.pl).
REGON Rejestr Gospodarki Narodowej (9 lub 14 cyfr) Główny Urząd Statystyczny (GUS) urn:pl:regon org-id.guide: schemat PL-REGON-&lt;numer&gt;. Weryfikacja i API: API REGON (stat.gov.pl).
KRS Krajowy Rejestr Sądowy Ministerstwo Sprawiedliwości (rejestr sądowy) urn:pl:krs Wyszukiwanie m.in. przez wyszukiwarkaregon.stat.gov.pl (po KRS).

Uwaga: NIP, REGON i KRS to polskie identyfikatory państwowe; ich przestrzeń nazw jest oddzielna od rejestrów HL7 (np. HL7 Terminology). Konwencja urn:pl:nip, urn:pl:regon i urn:pl:krs jest powszechnie stosowana w integracjach i spójna z rekomendacją używania URN dla identyfikatorów państwowych. Polska ma przypisane OID 1.2.616 (KRIO – Krajowy Rejestr Identyfikatorów Obiektów, PKN).

4.2 Stawki VAT (Polska)

Stawki VAT w Polsce wynikają z ustawy z 11 marca 2004 r. o podatku od towarów i usług oraz rozporządzeń Ministra Finansów. Oficjalne źródła:

Źródło Opis Adres
Matryca stawek VAT Wykaz stawek i zastosowań (m.in. zał. 3 i 10 do ustawy o VAT) podatki.gov.pl – Matryca stawek VAT
Lista stawek VAT Opis stawek i kategorii (SDG) podatki.gov.pl – List of VAT rates
Rozporządzenie MF – kody literowe Oznaczenia literowe stawek w kasach rejestrujących (fiskalnych) Rozporządzenie MF z 29.04.2019 r. w sprawie kas rejestrujących (Dz.U. poz. 816)

Kody literowe (rozporządzenie MF) – oficjalny słownik dla kas i systemów fiskalnych:

Litera Znaczenie Stawka / status
A Stawka podstawowa 23%
B Stawka obniżona 8%
C Stawka obniżona 5%
D Stawka obniżona 0%
E Zwolnienie od podatku zwolnienie
F, G Pozostałe (np. 0% techniczne) wg przepisów

Rekomendacja dla API-ERP:
Dla atrybutów typu „stawka VAT” można przyjąć:

  • Wartość procentowa (23, 8, 5, 0) – system lokalny np. https://api-erp.kamsoft.pl/ns/vat-rate z kodami liczbowymi lub opisowymi, z odwołaniem do oficjalnej matrycy MF w dokumentacji.
  • Kod literowy (A–G) – w integracji z kasami fiskalnymi używać oficjalnych liter z rozporządzenia MF; można zdefiniować system np. https://api-erp.kamsoft.pl/ns/vat-rate-fiscal z value setem A, B, C, D, E, F, G i odniesieniem do Dz.U. 2019 poz. 816.

Stawki procentowe (23%, 8%, 5%, 0%) nie mają jednego oficjalnego „URI słownika” wydanego przez MF; matryca stawek VAT na podatki.gov.pl jest aktualnym wykazem zastosowań.