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”). Value set jednoznacznie określa, które kody z systemu są dozwolone w API i w walidacji (np. Document.type w profilu FK wyłącznie 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-component-type | Typ elementu komponentu adresu (street, building-number, apartment-number, entrance, floor, district) | Address.component |
| address-use | Zastosowanie adresu (work, billing, home) | Address |
| address-type | Typ adresu (physical) | 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 na InventoryDocument — GR, GI, przesunięcie, korekta. | 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 | 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 |
| price-type | Rodzaj ceny w pozycji price[] (unit-price-net, promotional, purchase-net…) | ProductPricing.price |
| product-pricing-context | Kontekst zestawu cen produktu (sale, purchase, channel-retail…) | ProductPricing.context |
| 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 — etap realizacji pozycji (kody numeryczne z systemu magazynowego źródłowego). | PurchaseOrderPosition |
| purchase-order-realization-step | Stopień realizacji nagłówka zamówienia — kompletność realizacji (niezależnie od statusu workflow). | PurchaseOrder |
| purchase-order-status | Status workflow nagłówka zamówienia zakupu (kody numeryczne z systemu magazynowego źródłowego). | 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 |
| training-record | Dokumentacja szkolenia |
| workflow-approval | Zatwierdzenie w obiegu |
| decree | Dekret księgowy |
GR / GI: przyjęcie i wydanie towaru nie są typami document-type na zasobie Document — wyłącznie InventoryDocument z movementType receipt / issue (zob. InventoryDocument).
document-status
| Code | Opis |
|---|---|
| issued | Wystawione |
| completed | Zrealizowane |
| approved | Zatwierdzony |
posting-instruction-status
Używany w PostingInstruction.status (instrukcja księgowania EOD → FKW; zob. PostingInstruction). System kodów (propozycja): https://api-erp.kamsoft.pl/ns/posting-instruction-status.
| Code | Opis |
|---|---|
| proposed | Przekazano / oczekuje przetworzenia |
| accepted | Zaakceptowano parametry |
| rejected | Odrzucono (walidacja) |
| posted | Zaksięgowano |
| cancelled | Anulowano |
inventory-movement-type
Używany w InventoryDocument.movementType. Jednoznaczne oznaczenia angielskie: GR (goods receipt), GI (goods issue).
| Code | Opis | Oznaczenie |
|---|---|---|
| receipt | Przyjęcie towaru | GR (goods receipt) |
| issue | Wydanie towaru | GI (goods issue) |
| transfer | Przesunięcie między lokalizacjami | Stock transfer |
| adjustment | Korekta stanu | Inventory adjustment |
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 |
| decree-line | Wiersz dekretu na Document (nie stosować do dekretacji faktury w kanonie API.ERP — tam wyłącznie PostingInstruction.postingLine[]) |
GR / GI: pozycji ruchu magazynowego nie zapisuje się w Document.position — pola pozycji: InventoryDocument.position[] (InventoryDocumentPosition).
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-name
| Code | Opis |
|---|---|
| official | Nazwa oficjalna |
| short | Nazwa skrócona |
| trade | Nazwa handlowa |
| legal | Nazwa prawna / rejestrowa |
| former | Nazwa historyczna |
address-component-type
| Code | Opis |
|---|---|
| street | Ulica |
| building-number | Numer budynku |
| apartment-number | Numer lokalu |
| entrance | Klatka / wejście |
| floor | Piętro |
| district | Dzielnica / osiedle |
address-use
| Code | Opis |
|---|---|
| work | Siedziba / służbowy |
| billing | Rozliczeniowy |
| home | Prywatny |
address-type
| Code | Opis |
|---|---|
| physical | Fizyczny |
contact-point-system
| Code | Opis |
|---|---|
| phone | Telefon |
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 | Typy Document w WMS wyłącznie poza GR/GI (np. zapotrzebowania); GR/GI → InventoryDocument.movementType |
wg ValueSet (bez ruchu magazynowego na Document) |
| 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 — nie dla dekretacji faktury (→ PostingInstruction) | 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 (GR), issue (GI), 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 |
| oh-exam-type | OID 1.2.616.1.113769.1.9 |
MP — profil CDA skierowania (sekcja 1, purpose.exam_type_code) |
01–06 — rodzaje badania; JSON |
| oh-exposure-group | OID 1.2.616.1.113769.1.8.1 |
MP — sekcja 3 (organizer CLUSTER) | 01–05 — grupy czynników; JSON |
| oh-exposure-factor | OID 1.2.616.1.113769.1.8.2 |
MP — sekcja 3 (observation czynnika) | słownik centralny (IG: kody z przykładów v0.3; pełny katalog w master data); JSON |
| oh-profile-section1-code | OID 1.2.616.1.113769.5.1.1 |
MP — sekcja 1 (daty kontekstowe) | LAST-EXAM-DATE, EXAM-VALID-UNTIL; JSON |
| oh-profile-section3-code | OID 1.2.616.1.113769.5.1.3 |
MP — sekcja 3 (struktura narażeń) | ALL-EXPOSURES, EXPOSURE-TIME, EXPOSURE-DESC; JSON |
| oh-profile-section4-code | OID 1.2.616.1.113769.5.1.4 |
MP — sekcja 4 (badania dodatkowe) | ADD-EXAMS, ADDITIONAL-EXAMS; JSON |
| oh-profile-section5-code | OID 1.2.616.1.113769.5.1.5 |
MP — sekcja 5 (informacje dodatkowe) | ADDITIONAL-INFO; JSON |
Uwaga: Powyższe value sety są kontekstowym doprecyzowaniem code systemów. W API i schematach (OpenAPI/JSON Schema) pole wiąże się z value setem zgodnie z profilem (np. Document.type w profilu FK z DocumentType-FK), co 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 profilu zasobu.
3. Powiązanie z modelami
Dopuszczalne wartości w polach CodeableConcept/Identifier w poszczególnych zasobach wynikają z 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-component-type, address-use, 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 (np. numer GR / GI / 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).
- MP (e-skierowanie medycyny pracy, profil CDA) → value sety
oh-exam-type,oh-exposure-group,oh-exposure-factor,oh-profile-section1-code,oh-profile-section3-code,oh-profile-section4-code,oh-profile-section5-code(OID jakocodeSystemw CDA; zob. profil CDA MP). Zestawy lokalne klienta (oh-exposure-factor-client,oh-work-position) — URL stabilny, treść poza IG.
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 stosuje się oficjalne źródła oraz — tam gdzie występują — oficjalne lub powszechnie przyjęte systemy (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-<numer>. 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-<numer>. 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” stosuje się:
- Wartość procentowa (23, 8, 5, 0) – system lokalny np.
https://api-erp.kamsoft.pl/ns/vat-ratez kodami liczbowymi lub opisowymi, z odwołaniem do oficjalnej matrycy MF w dokumentacji. - Kod literowy (A–G) – w integracji z kasami fiskalnymi: oficjalne litery z rozporządzenia MF; system np.
https://api-erp.kamsoft.pl/ns/vat-rate-fiscalz value setemA,B,C,D,E,F,Gi 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ń.