Identyfikacja i parametry wdrożenia

Ten rozdział wyjaśnia, co w integracji z API.ERP jest stałe (i opisane w tym IG), a co jest parametrem konkretnej instalacji — oraz skąd integrator bierze wartości tych parametrów.

1. Problem: `system` identyfikatora jest parametrem instalacji

Dane w API.ERP identyfikują się przez Identifier (system + value). Część przestrzeni system jest stała i wspólna (rejestry publiczne jak https://gov.pl/nip), ale przestrzenie identyfikatorów kartotek konkretnej instalacji (kontrahenci, środki trwałe, bufory dokumentów, rejestry FK…) — czyli OIDy/URI nadawane per środowisko — nie są i nie mogą być częścią IG. Zob. Identifier — skąd pochodzi wartość system.

Stabilnym wymiarem dokumentacji jest klucz przestrzeni (Party.Id, Invoice.Id, FixedAsset.Id…). IG dokumentuje na stronie każdego zasobu, które przestrzenie zasób niesie; instalacja publikuje mapowanie przestrzeń → faktyczny system jako zasoby NamingSystem (GET /v1/naming-systems, rozdział 2b). Rodzaj identyfikatora wynika z przestrzeni — Identifier.type go nie niesie (zgodnie z FHIR: opcjonalny kod v2-0203, np. TAX).

Analogiczna sytuacja dotyczy części słowników: URL słownika jest stabilny i wspólny, ale lista kodów (symbole dokumentów, jednostki miary, rodzaje majątku, typy zatrudnienia) powstaje per instalacja.

2. Profile zasobów

Dla integratora istnieje jeden produkt: API.ERP. Integrator nie wskazuje systemu ani instalacji i nigdzie ich nie widzi.

Rodzaj zasobu opisuje profil, opublikowany jako schemat JSON pod swoim adresem (profile kanoniczne). Zasób niesie meta.profile — listę adresów kanonicznych profili, karta wymienia obsługiwane profile w rest[].resource[].supportedProfile, a wyszukiwanie zawęża standardowy parametr profile. Przykład: strona ma profile Employee, Employer, Contractor i AssetHolder; lokalizacja ma Warehouse, StorageLocation i UsagePlace.

Zasady wywołań:

GET /v1/parties?profile=<adres profilu> zwraca zasoby tego profilu; bez profile wszystkie obsługiwane profile zasobu. Nieznany profile kończy się 400; profil znany, ale bez miejsca prawdy u klienta — 422.
Zapis: zasób z meta.profile musi spełniać wymagania profilu; bez meta.profile API rozpoznaje profil po treści (np. category ze słownika party-kind). Profil nieobsługiwany u klienta kończy się 422.
Przestrzeń identyfikatora wewnętrznego (urn:oid:1.2.616.1.113769.4.…) należy do instalacji obsługującej profil. Wyszukiwanie identifier=<przestrzeń>|<wartość> z inną przestrzenią kończy się 404.

Co wyznacza instalację obsługującą żądanie

Instancja API.ERP pracuje zawsze dla jednego klienta: klienta wyznacza sama instancja, a nie treść wywołania. Integrator nie przekazuje go żadnym parametrem ani nagłówkiem i nigdzie go nie widzi.

W instalacji klienta może natomiast pracować kilka systemów źródłowych. To, który z nich obsłuży żądanie, rozstrzyga sama treść wywołania — inaczej w odczycie, inaczej w zapisie.

Odczyt: trzy tory

O zakresie odczytu decyduje para zawężeń profile i identifier:

Co podaje integrator w odczycie	Kto odpowiada	Czego się spodziewać
parametr `profile`	tylko pierwszy w kolejności system honorujący ten profil (kolejność z parametrów wdrożenia, rozdział 4)	odpowiedź jednego systemu; pozostałe systemy honorujące profil nie są odpytywane
parametr `identifier=<przestrzeń>\\|<wartość>` (przestrzeń OID)	wyłącznie instalacja wskazana tą przestrzenią	gdy wskazana instalacja nie prowadzi tego zasobu albo profilu — `404`
ani `profile`, ani `identifier`	wszystkie instalacje rozumiejące ten zasób	odpowiedź jest złączeniem tego, co zwróciły poszczególne instalacje

Tor bez zawężenia jest więc najszerszy, a nie domyślnie „pierwszy": jedna kolekcja może nieść zasoby pochodzące z kilku systemów naraz. Zawężenie profile sprowadza odpowiedź do jednego systemu, zawężenie identifier — do jednej wskazanej instalacji. Podanie obu naraz jest dopuszczalne: przestrzeń nadal musi należeć do miejsca prawdy tego profilu, w przeciwnym razie 404.

Zapis: profil wyznacza dziedzinę, przestrzeń wskazuje instalację

W POST i PATCH dziedzinę rozstrzyga profil (meta.profile albo profil rozpoznany po treści), a przestrzeń identyfikatora — gdy podana — wskazuje instalację, która zapis przyjmie; musi należeć do miejsca prawdy tego profilu, w przeciwnym razie 404. Gdy profil honoruje wiele systemów, a przestrzeni nie podano, zapis idzie do pierwszego istniejącego systemu w kolejności (rozdział 3).

Kolejność systemów jest informacją pozasystemową

Kolejność systemów honorujących ten sam profil jest parametrem wdrożenia przekazywanym przez opiekuna integracji KAMSOFT (rozdział 4) i nie wynika z żadnego endpointu: nie wyraża jej ani karta GET /v1/metadata, ani GET /v1/naming-systems, ani żadna inna dostępna specyfikacja. Integrator powinien tę kolejność znać — ale odczytać jej z API nie może. Chcąc odpytać system inny niż pierwszy, podaje przestrzeń identyfikatora.

Przestrzenie identyfikatorów w odpowiedzi należą do instalacji, która żądanie obsłużyła.

2a. Karta wdrożenia: `GET /v1/metadata`

GET /v1/metadata zwraca CapabilityStatement klienta w kształcie FHIR R5: zasoby z obsługiwanymi profilami, interakcjami, parametrami wyszukiwania i operacjami. Karta opisuje jeden produkt, API.ERP, i nie zawiera nazw systemów źródłowych. Karta nie niesie przestrzeni identyfikatorów (publikuje je NamingSystem, rozdział 2b), katalogu słowników (GET /v1/value-sets, ValueSet) ani trybów integracji — zakres wyrażają interaction i operation.

Pole	Kard.	Znaczenie
`status`	1..1	`active`
`kind`	1..1	`instance` — karta opisuje instalację klienta, nie ogólne możliwości oprogramowania
`date`	1..1	data wygenerowania karty (`yyyy-MM-dd`)
`format[]`	1..*	`application/json`
`software.name`, `software.version`	1..1, 0..1	`API.ERP` i wersja
`implementation.description`	1..1	opis instalacji
`implementation.custodian`	0..1	Reference do Party klienta: `identifier` w przestrzeni `https://gov.pl/nip`
`rest[]`	1..1	jedna pozycja, `mode` = `server`
`rest[].resource[].type`	1..1	nazwa zasobu (np. `Party`)
`rest[].resource[].supportedProfile[]`	0..*	adresy obsługiwanych profili
`rest[].resource[].interaction[].code`	1..1	kod TypeRestfulInteraction: `search-type` = `GET` kolekcji z parametrami, `create` = `POST`, `patch` = `PATCH`; `read` nie występuje (brak odczytu po `id`)
`rest[].resource[].searchParam[]`	0..*	`name` i `type` z SearchParamType. `token`: `identifier`, `owner`, `profile`, `type`, `status`, `kind`, `category`, `attribute`, `role`, `system`, `url`, `id`, `coding`, `period` (numer okresu rozliczeniowego, nie data), `year`, `month`. `date`: `lastModified`, `statusDate`, `issueDateFrom`, `issueDateTo`, `dateFrom`, `dateTo`. `string`: `symbol`, `number`. `reference` (wartość `system\\|value` innego zasobu): `party`, `partyFrom`, `partyTo`, `participant`, `holder`, `assignedTo`, `granted`, `basedOn`, `scope`, `contained`, `postingInstruction`, `location`, `fromLocation`, `product`, `employeeId`, `organizationUnitId`, `costCenterNumber`, `costCarrierId`, `productGroupId`. Zasób z `supportedProfile` ma zawsze parametr `profile`
`rest[].resource[].operation[]`	0..*	operacje `$<name>` na kolekcji zasobu: `name` i `definition` = `https://api-erp.kamsoft.pl/ns/OperationDefinition/<name>`
`rest[].operation[]`	0..*	operacje poziomu systemu — raporty trybu raportowego (`POST /v1/reports`, `reportId` = `name`), `definition` jak wyżej

Celowe odstępstwa od R5:

Element R5	API.ERP	Powód
`fhirVersion` 1..1	brak	Kamsoft.FAIR nie jest FHIR; wersję modeli niesie `software.version`
`implementation.custodian` = Reference(Organization)	Reference(Party)	API.ERP nie ma zasobu Organization
`interaction[].code` obejmuje `read`, `update`, `delete`	tylko `search-type`, `create`, `patch`	brak tras z `{id}`, `PUT` i `DELETE`

{ "resourceType": "CapabilityStatement", "status": "active", "kind": "instance", "date": "2026-09-18",
  "format": ["application/json"],
  "software": { "name": "API.ERP", "version": "1.x" },
  "implementation": { "description": "API.ERP deployment",
    "custodian": { "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "<NIP>" } } },
  "rest": [ { "mode": "server",
    "resource": [
      { "type": "Party",
        "supportedProfile": [ "https://api-erp.kamsoft.pl/ns/StructureDefinition/Contractor",
                              "https://api-erp.kamsoft.pl/ns/StructureDefinition/Employee" ],
        "interaction": [ { "code": "search-type" }, { "code": "create" }, { "code": "patch" } ],
        "searchParam": [ { "name": "identifier", "type": "token" }, { "name": "owner", "type": "token" },
                         { "name": "profile", "type": "token" }, { "name": "lastModified", "type": "date" } ] },
      { "type": "FixedAssetDocument",
        "interaction": [ { "code": "search-type" }, { "code": "create" }, { "code": "patch" } ],
        "searchParam": [ { "name": "identifier", "type": "token" }, { "name": "owner", "type": "token" } ],
        "operation": [ { "name": "document-content",
                         "definition": "https://api-erp.kamsoft.pl/ns/OperationDefinition/document-content" } ] } ],
    "operation": [ { "name": "cost-calculation",
                     "definition": "https://api-erp.kamsoft.pl/ns/OperationDefinition/cost-calculation" } ] } ] }

Definicja operacji (FHIR R5 OperationDefinition) jest do pobrania spod adresu definition; ten przewodnik publikuje je w operations/ (document-content, cost-calculation, product-level-cost-calculation).

2b. Przestrzenie identyfikatorów: `GET /v1/naming-systems`

Każda przestrzeń identyfikatorów instalacji to jeden zasób NamingSystem (FHIR R5). Lista: GET /v1/naming-systems; zawężenie do zasobu: ?usage=Party.

Pole	Konwencja API.ERP
`name`	klucz przestrzeni — ten sam, który stoi w tabelach „Identyfikatory" na stronach zasobów (np. `Party.Id`)
`usage`	nazwa zasobu, którego identyfikatory niesie przestrzeń (np. `Party`)
`description`	znaczenie przestrzeni, po angielsku (np. „Contractor id in the accounting ledger") — rozróżnia przestrzenie o tym samym `name` (osobna dla każdego profilu strony)
`uniqueId[].value`	dosłownie wartość `Identifier.system`: `urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>`
`uniqueId[].preferred`	`true` = klucz referencyjny: `value` w przestrzeni unikalne, przestrzeń nadaje się do `?identifier=system\|value`

Wiersz tabeli „Identyfikatory" na stronie zasobu odpowiada zasobowi NamingSystem o tym samym name, usage i znaczeniu. Rodzaj identyfikatora wynika z przestrzeni — karta ani NamingSystem nie niosą go osobnym polem.

{ "resourceType": "NamingSystem", "name": "Party.Id", "status": "active", "kind": "identifier", "date": "2026-09-18",
  "description": "Contractor id in the accounting ledger", "usage": "Party",
  "uniqueId": [ { "type": "uri", "value": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>", "preferred": true } ] }

3. Rejestracja zasobu: wartość identyfikatora nadaje system prowadzący

Przestrzeń identyfikatora jest opcjonalna. Gdy jej nie podano, instalację rozstrzyga profil zasobu — w treści wskazany adresem kanonicznym w meta.profile — a przy wielu systemach honorujących profil odpowiada pierwszy istniejący (rozdział 2). Gdy jest podana — w POST w treści, jako identifier[].system — wskazuje instalację, która zarejestruje zasób, i jest jednocześnie potwierdzeniem: musi należeć do miejsca prawdy profilu, w przeciwnym razie 404. Podanie przestrzeni jest zalecane wszędzie tam, gdzie profil prowadzi w instalacji więcej niż jeden system.

Wartości identyfikatora wewnętrznego integrator nie wymyśla: value przy rejestracji jest opcjonalne — nadaje je system prowadzący i zwraca w odpowiedzi. Firmę prowadzącą kartotekę wskazuje parametr owner (NIP):

POST /v1/parties?owner=https://gov.pl/nip%7C1234567890

{ "resourceType": "Party",
  "meta": { "profile": ["https://api-erp.kamsoft.pl/ns/StructureDefinition/Contractor"] },
  "identifier": [{ "system": "urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>" }],
  "name": { "text": "Przykład sp. z o.o." } }

Co wysyłasz	Co się dzieje
`identifier` z samą przestrzenią, bez `value`	powstaje nowy zasób w instalacji wskazanej przestrzenią, a wartość nadaje system prowadzący; odpowiedź zawiera nadany identyfikator
`identifier` z `system` i `value` w treści `POST`	wartość jest ignorowana, powstaje nowy zasób; aktualizacja to `PATCH` z parametrem `identifier=system\\|value`
`identifier` bez `system` albo brak `identifier`	powstaje nowy zasób; instalację i dziedzinę rozstrzyga profil, a przy wielu systemach honorujących profil odpowiada pierwszy istniejący
przestrzeń spoza miejsca prawdy profilu	`404`: przestrzeń nie należy do miejsca prawdy tego profilu

Aktualizacja idzie osobną operacją: PATCH /v1/parties?identifier=<przestrzeń>|<wartość> z treścią zmian. Tu przestrzeń wraz z wartością wskazuje zasób do zmiany, więc parametr identifier jest konieczny; przestrzeń musi należeć do miejsca prawdy profilu.

Przestrzeń może więc wskazać miejsce zapisu i jest wtedy jednocześnie potwierdzeniem: albo zgadza się z miejscem prawdy profilu, albo żądanie jest odrzucane (404). Gdy jej nie podano, rozstrzyga profil — zapis bez rozpoznanego profilu kończy się błędem 400, bo nie wiadomo, o którą dziedzinę chodzi.

4. Parametry wdrożenia

Parametry wdrożenia to zestaw wartości specyficznych dla instalacji, przekazywany integratorowi przez opiekuna integracji KAMSOFT razem z danymi dostępowymi:

Parametr	Do czego służy
Kolejność systemów honorujących ten sam profil	rozstrzyga, który system odpowiada, gdy profil prowadzi w instalacji więcej niż jeden system: w odczycie z parametrem `profile` i w zapisie bez wskazanej przestrzeni odpowiada pierwszy istniejący (rozdział 2). Nie wyraża tej kolejności żaden endpoint — ani karta `GET /v1/metadata`, ani `GET /v1/naming-systems`; integrator dostaje ją wyłącznie od opiekuna integracji KAMSOFT. Sam jej nie podaje; chcąc wskazać inny system, podaje przestrzeń identyfikatora
Obsługiwane profile zasobów, interakcje, parametry wyszukiwania i operacje	do odczytu z karty wdrożenia `GET /v1/metadata`, `rest[].resource[]` (rozdział 2a)
Przestrzenie identyfikatorów (`system`) per zasób i klucz przestrzeni	do odczytu z `GET /v1/naming-systems` (NamingSystem, rozdział 2b): budowanie i rozstrzyganie referencji logicznych; podstawienie w miejsce placeholderów z przykładów IG
Wskazanie, które przestrzenie są kluczem referencyjnym (`NamingSystem.uniqueId[].preferred = true`)	wyszukiwanie `GET /v1/<kolekcja>?identifier=system\|value` wymaga unikalności `value` w przestrzeni
Zakres udostępnionych zasobów, interakcji i operacji	wynika z umowy, odzwierciedla go karta (`interaction`, `operation`); wywołanie poza zakresem kończy się `403 Forbidden`

Treść słowników wdrożeniowych nie jest przekazywana dokumentem — pobiera się ją z API: GET /v1/value-sets?url=<url> dla wskazanego słownika albo bez parametru url dla listy słowników instalacji (wymagana rola API.ValueSet.Read).

5. Placeholdery `urn:oid:2.999.*` w przykładach IG

Przykłady w IG nie mogą używać prawdziwych OIDów instalacji, więc przestrzenie wdrożeniowe reprezentują placeholdery urn:oid:2.999.<n> (łuk OID 2.999 jest zarezerwowany do celów przykładowych); każda strona przykładów ma własną lokalną legendę — zob. Konwencje przykładów.

Parametry wdrożenia domykają tę konwencję: każdemu placeholderowi z przykładów odpowiada we własnej integracji konkretna przestrzeń otrzymana od KAMSOFT. Dopasowanie danych do parametrów wykonuje się po wartości system — to jedyny łącznik gwarantowany w każdej instalacji.

6. Rozstrzyganie referencji (skrót)

Referencja logiczna to para (type, identifier{system, value}). Rozstrzyga się ją wyszukiwaniem na kolekcji zasobów danego typu: GET /v1/<kolekcja>?identifier=system|value. Wartość system do takiego wyszukiwania pochodzi z NamingSystem instalacji (uniqueId[].value przestrzeni z preferred = true). Pełna reguła, interpretacja wyników (brak / jedno / wiele trafień) i przykłady: Reference — rozstrzyganie referencji.

7. Gdzie czego szukać

Informacja	IG (ten przewodnik)	Parametry wdrożenia / API	Portal APIM
Model zasobów, pola, kardynalności	✔ (strony zasobów, profile)	—	—
Trasy, metody, parametry wyszukiwania	✔ (Kontrakty API); per instalacja w karcie: `rest[].resource[].interaction[]`, `searchParam[]` (`name`, `type`), `operation[]`	✔ (`GET /v1/metadata`)	✔ (Portal dla Integratorów)
Nagłówki wspólne wywołań, paginacja, błędy	✔ (Konwencje techniczne)	—	—
Przestrzenie identyfikatorów per zasób (klucze)	✔ (tabele „Identyfikatory" na stronach zasobów, NamingSystem)	✔ (`GET /v1/naming-systems`: `name`, `usage`, `uniqueId[].value`, `uniqueId[].preferred`, `description`)	—
Faktyczne przestrzenie `Identifier.system` instalacji	placeholdery `2.999.*`	✔ (`GET /v1/naming-systems`)	—
URL-e i treść słowników utrzymywanych centralnie	✔ (code-systems, `docs/vs/`)	—	—
Treść słowników ustalanych per instalacja	tylko URL i opis	✔ (`GET /v1/value-sets?url=`)	—
Zakres zasobów, interakcji i operacji w danej instalacji	pełen katalog możliwości	✔ (`GET /v1/metadata`: `interaction[]`, `operation[]`)	katalog produktów API
Rejestracja aplikacji, klucze relacji, uprawnienia	zasady (Bezpieczeństwo)	—	✔ (App Registry, instrukcja rejestracji)

8. Odniesienia

Identifier · Reference · NamingSystem · ValueSet · Systemy kodowania i value sety
FHIR R5 CapabilityStatement · FHIR R5 NamingSystem · FHIR R5 OperationDefinition
Tryby API.ERP · Konwencje techniczne · Konwencje przykładów