Printer icon

nAxiom PublicAPI – kompletny przewodnik użytkownika

📅 2026-05-06 sygnet.svg 1.15.6.4


Przeczytasz w 40 min.

Spis treści

Wprowadzenie

nAxiom PublicAPI to interfejs REST przeznaczony do integracji systemów zewnętrznych z platformą nAxiom. Pozwala m.in. odczytywać i modyfikować dokumenty, zarządzać załącznikami, profilami użytkowników, uprawnieniami menu oraz strukturą organizacyjną.

Adres bazowy serwisu PublicAPI to katalog /publicapi/ na hoście instancji nAxiom, np.:

https://naxiom.mojafirma.pl/publicapi/

Dokumentacja Swagger dostępna jest pod tym samym adresem w przeglądarce — pozwala interaktywnie sprawdzać schematy żądań i odpowiedzi. Aby uzyskać token, należy kliknąć przycisk Authorize, wpisać id klienta public-api-swagger i zaznaczyć zakres public-api. Po kliknięciu przycisku Authorize zostanie wyświetlone okno logowania do nAxiom. Po zalogowaniu nastąpi powrót do strony Swaggera, a w opisach poszczególnych endpointów będzie dostępny przycisk Try It Out.

Nie wszystkie endpointy widoczne w dokumentacji Swagger zostały opisane w tym artykule. Działanie niektórych nie zostało jeszcze potwierdzone w środowisku testowym, a niektóre utworzono wyłącznie na potrzeby integracji (np. Esign, Epuap). Patrz także sekcja Lista zweryfikowanych endpointów na końcu artykułu.

Konfiguracja środowiska

Klient auth

Aby w ramach integracji można było pobrać token, w pliku appsettings.json serwisu auth (lub odpowiadającej mu konfiguracji w środowiskach kontenerowych) musi istnieć klient z dozwolonym scope public-api. Przykładowy wpis (sekcja Clients):

{
  "ClientId": "public-api-swagger",
  "ClientName": "PublicAPI Client",
  "AllowedGrantTypes": "Implicit",
  "SecretKeySha256": "secret",
  "AllowAccessTokensViaBrowser": true,
  "CanUseReferenceAccessToken": false,
  "RequireConsent": false,
  "AlwaysIncludeUserClaimsInIdToken": true,
  "RequireClientSecret": false,
  "AllowedScopes": [ "public-api" ]
}

Jeśli wymagasz dodatkowego zabezpieczenia kluczem klienta, włącz RequireClientSecret: true i zdefiniuj zaszyfrowany sekret w appsettings-protected.json.

  "AppConfiguration": {
    "Secrets": {
      ...,
      "Client-publicApiClient": "DVqipgOwCBz9D3JS..."
    }
  }

Informacje dotyczące szyfrowania hasła można uzyskać u producenta nAxiom.

Taka konfiguracja spowoduje, że w żądaniu tokenu konieczne będzie podanie hasła klienta jako wartości klucza client_secret.

Po każdej zmianie appsettings.json należy zrestartować serwis auth (IIS, Docker, Kubernetes, OpenShift) — konfiguracja jest wczytywana przy starcie.

Wymagania dotyczące profilu użytkownika Public API

Konto, które będzie używane do logowania w PublicAPI, musi spełniać poniższe warunki:

  1. Włączony przełącznik Dostęp do Public API w profilu użytkownika.
  2. Aktywne konto (niezablokowane, nieprzeterminowane).
  3. Odpowiednie uprawnienia ACL do dokumentów, które będzie przetwarzać.
  4. Odpowiednie uprawnienia PBA (np. do edycji profili).
  5. Endpointy w grupach /User/, */Permission/ oraz */PermissionDelegation/** wymagają dodatkowo przypisanej roli biznesowej System - Administrator użytkowników PublicAPI (kod *USER_ADMIN_PUBLICAPI). Bez tej roli wywołanie endpointów administracyjnych zwróci HTTP 400 z kodem Api.Public.InsufficientPermissions.
  6. Endpoint POST /Document/CreateNewSchema wymaga uprawnienia systemowego Budowanie aplikacji → Przegląd aplikacji w module AdminSPA (wewnętrzny kod AllAppManagement)1. Bez niego serwis odpowie HTTP 400 z kodem Api.Shared.NoPermissions.

Uwierzytelnianie i token JWT

Pobranie tokenu

Token jest wydawany przez serwis auth instancji nAxiom pod adresem /connect/token. Żądanie:

  • Metoda: POST
  • Content-Type: application/x-www-form-urlencoded
  • Body (parametry urlencoded):
    • grant_type = password
    • username = nazwa użytkownika integracyjnego
    • password = hasło użytkownika
    • scope = public-api
    • client_id = identyfikator klienta z appsettings.json (np. publicApiClient)
    • client_secret = sekret klienta (tylko gdy RequireClientSecret=true)

Przykład — curl:

curl -k --location 'https://naxiom.mojafirma.pl/connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'username=integracja' \
  --data-urlencode 'password=<HASŁO>' \
  --data-urlencode 'scope=public-api' \
  --data-urlencode 'client_id=publicApiClient' \
  --data-urlencode 'client_secret=<SEKRET_KLIENTA>'

Parametr -k wyłącza weryfikację certyfikatu — używaj tylko w środowiskach testowych z certyfikatem samopodpisanym. W produkcji użyj poprawnego certyfikatu i pomiń -k.

W odpowiedzi otrzymasz JSON zawierający access_token, expires_in i token_type. Wartość access_token przekazujesz w nagłówku Authorization przy każdym kolejnym wywołaniu PublicAPI.

Czas życia tokenu

Czas życia tokenu zależy od konfiguracji serwera tożsamości. Najczęściej spotykane wartości to 900 s (15 min) lub 3600 s (60 min) — patrz expires_in w odpowiedzi. Po wygaśnięciu należy ponownie wywołać /connect/token.

Użycie tokenu

Każde żądanie do PublicAPI musi mieć nagłówek:

Authorization: Bearer <access_token>

W dalszej części artykułu dla zwięzłości będzie używany placeholder ** w miejsce pełnej wartości.

Konwencje używane w przykładach

  • Adres bazowy w przykładach zastąp https://naxiom.mojafirma.pl własnym adresem instancji.
  • Identyfikatory (np. documentDefinitionId=3025) — w Twoim środowisku będą inne. Sprawdź we Front SPA lub w bazie nAxiom.
  • Daty podaje się w formacie ISO 8601 (2026-04-25T10:00:00).
  • Format odpowiedzi: JSON, kodowanie UTF-8.
  • Błędy walidacji: serwis zwraca tablicę obiektów { propertyName, errorMessage, … } z kodem HTTP 400. Klucze errorMessage rozpoczynające się od Api. mają przetłumaczone komunikaty.

Endpointy dokumentów (/Document)

Dokument biznesowy w nAxiom jest powiązany z tabelą SQL i definicją formularza. Endpointy operują na instancjach dokumentów (rekordach tabeli) z weryfikacją uprawnień ACL i uwzględnieniem diagramu procesu (workflow).

Konwencja nazewnicza

Parametr documentDefinitionId w różnych endpointach może oznaczać ID dokumentu biznesowego (np. 3025, klucz tabeli BusinessDocument) lub ID definicji formularza (np. 3024, klucz tabeli FormDefinition). W każdej sekcji jest to wyraźnie zaznaczone.

GET /Document/GetSchema — projekt tabeli dokumentu

Zwraca listę kolumn tabeli powiązanej z definicją dokumentu (kolumny systemowe i biznesowe).

Parametr query Typ Wymagane Opis
documentDefinitionId int tak ID definicji dokumentu

Odpowiedź 200 OK: lista właściwości kolumn (nazwa, typ SQL, nullable itd.).

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/GetSchema?documentDefinitionId=3025' \
  --header 'Authorization: Bearer <TOKEN>'

GET /Document/Get — odczyt instancji dokumentu

Zwraca pełne dane jednej instancji dokumentu w formacie JSON.

Parametr query Typ Wymagane Opis
documentDefinitionId int tak ID definicji formularza (nie ID definicji dokumentu!)
recordId int tak ID instancji

Odpowiedź 200 OK: ciąg JSON zawierający tablicę z dokładnie jednym obiektem ([{…}]). Pola obiektu odpowiadają kolumnom tabeli.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/Get?documentDefinitionId=3024&recordId=1' \
  --header 'Authorization: Bearer <TOKEN>'

POST /Document/Save — utworzenie lub aktualizacja

Dodaje nową instancję (recordId=0) lub aktualizuje istniejącą (recordId>0).

Parametr query Typ Wymagane Opis
documentDefinitionId int tak ID definicji dokumentu
recordId int tak ID rekordu lub 0 dla nowego
rowVersion int nie Aktualna wersja rekordu (dla optimistic concurrency); 0 dla nowego
skipWorkflowActionsForNewRecord bool nie Pominięcie akcji workflow przy tworzeniu nowego rekordu

Body: obiekt JSON, w którym klucze to nazwy kolumn tabeli, a wartości to wartości kolumn.

Body powinno zawierać wszystkie kolumny biznesowe wymagane (NOT NULL bez wartości domyślnej). Kolumny systemowe (Id, RowGuid, CreatedBy, CreatedDate, RowVersion itp.) są zarządzane automatycznie i nie powinny być przekazywane.

Odpowiedź 200 OK: ciąg z ID utworzonego/zaktualizowanego rekordu (np. “1”).

Przykład — nowy rekord:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/Save?documentDefinitionId=3025&recordId=0' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{
    "ReservationNumber": "1",
    "StartDate": "2026-04-25",
    "EndDate": "2026-04-25",
    "ReservedBy": "adam",
    "Purpose": "test",
    "Attendees": 1,
    "IsRecurring": false,
    "Notes": "testowa notatka"
  }'

Przykład — aktualizacja:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/Save?documentDefinitionId=3025&recordId=1&rowVersion=2' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{
    "ReservedBy": "adam-upd",
    "Purpose": "test po aktualizacji",
    "Attendees": 2
  }'

POST /Document/CreateWithAttachments — utworzenie z załącznikami

Tworzenie nowej instancji dokumentu i dodanie do niej załączników. Błąd któregokolwiek załącznika powoduje wycofanie całej operacji.

Wymaga, aby użytkownik miał uprawnienia do aktualizacji rekordu (U) w pierwszym statusie. (Najpierw tworzy instancję dokumentu, następnie dodaje do niej załączniki).

Parametr query Typ Wymagane Opis
documentDefinitionId Guid tak RowGuid definicji dokumentu (nie ID liczbowe!)
batchId Guid nie ID operacji wsadowej do audytu; gdy pominięte – generowane
skipWorkflowActions bool nie Pominięcie akcji workflow

Body:

{
  "Model": {
    "ReservedBy": "adam",
    "Purpose": "test",
    "StartDate": "2026-04-25",
    "EndDate": "2026-04-25",
    "Attendees": 1,
    "IsRecurring": false,
    "Notes": "test"
  },
  "Attachments": [
    {
      "Base64Content": "SGVsbG8gV29ybGQ=",
      "FileName": "test.txt",
      "Description": "Plik testowy",
      "AttachmentCategoryId": null
    }
  ]
}

Pole Id w Model jest zawsze ignorowane — serwis sam nadaje nowy ID. AttachmentCategoryId jest opcjonalne — pominięcie spowoduje użycie kategorii domyślnej dokumentu.

Odpowiedź 200 OK: obiekt CreateWithAttachmentsResponseDto z polami:

  • RecordId — ID utworzonego rekordu (string),
  • BusinessDocumentGuid — RowGuid definicji,
  • Model — pełen model po zapisie (z polami systemowymi),
  • Attachments — tablica { FileName, Id },
  • BatchId,
  • SkipWorkflowActions.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/CreateWithAttachments?documentDefinitionId=c87d78ed-cc0a-4c85-b77e-a489bb4a7e7e&skipWorkflowActions=true' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{
    "Model": {
      "ReservedBy": "adam",
      "Purpose": "test",
      "StartDate": "2026-04-25",
      "EndDate": "2026-04-25",
      "Attendees": 1,
      "IsRecurring": false
    },
    "Attachments": [
      { "Base64Content": "SGVsbG8gV29ybGQ=", "FileName": "test.txt", "Description": "test" }
    ]
  }'

POST /Document/GetFormById — definicja formularza z danymi

Zwraca definicję formularza wraz z danymi instancji oraz informacjami o uprawnieniach zalogowanego użytkownika do tej instancji.

Parametr query Typ Wymagane Opis
id int tak ID definicji formularza
recordId string tak ID instancji dokumentu

Body: ciąg JSON z dodatkowym kontekstem (zwykle pusty ”{}”).

Odpowiedź 200 OK: obiekt z definicją formularza, danymi rekordu i flagami CRUD.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/GetFormById?id=3024&recordId=1' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '"{}"'

GET /Document/GetStatus — bieżący status instancji

Parametr query Typ Wymagane Opis
documentId int tak ID dokumentu biznesowego
recordId int tak ID instancji

Odpowiedź 200 OK: obiekt statusu z polami id, code, fullName, description, businessDocumentId, active.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/GetStatus?documentId=3025&recordId=1' \
  --header 'Authorization: Bearer <TOKEN>'

GET /Document/GetTransitions — dostępne przejścia

Zwraca listę przejść dostępnych z bieżącego statusu rekordu dla ról zalogowanego użytkownika. Jeśli nie ma dostępnych przejść, zwraca pustą listę [].

Parametr query Typ Wymagane
documentDefinitionId int tak
recordId int tak

Odpowiedź 200 OK: tablica obiektów BusinessTransitionDto. Najważniejsze pola każdego elementu:

  • id — ID przejścia (używane w ChangeStatus),
  • buttonName — nazwa przycisku (np. „Zatwierdź”, „Anuluj”),
  • fromStatus, toStatus — pełne obiekty statusu (id, code, description),
  • roles — role uprawnione do wywołania,
  • actions — akcje wykonywane przy przejściu,
  • buttonSettings — formatowanie przycisku w UI.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/GetTransitions?documentDefinitionId=3025&recordId=1' \
  --header 'Authorization: Bearer <TOKEN>'

GET /Document/GetFormTransitions — jak GetTransitions

Endpoint przeznaczony do obsługi pluginu MS Oulook. Działa tak samo jak GetTransitions Jedyna istotna różnica biznesowa: GetFormTransitions pozwala przekazać bieżący stan formularza (niezapisane dane) do oceny warunków SQL wyświetlania przycisków; GetTransitions tego nie wspiera — przy zdefiniowanym warunku SQL z parametrami opartymi o pola formularza zwróci błąd UndefinedParameterInSQLQuery.

Parametr query Typ Wymagane
documentId int tak
recordId int tak
context string nie

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/GetFormTransitions?documentId=3025&recordId=1' \
  --header 'Authorization: Bearer <TOKEN>'

POST /Document/ChangeStatus — zmiana statusu

Wykonuje przejście statusu i powiązane akcje workflow.

Parametr query Typ Wymagane Opis
documentDefinitionId int tak ID dokumentu biznesowego
recordId int tak ID instancji
transitionId int tak ID przejścia (z GetTransitions)
formId int nie Domyślnie -1

Body: ten sam format co w Save — pola modelu dokumentu (kolumny biznesowe).

Odpowiedź 200 OK: lista akcji do wykonania na froncie, lub true, jeśli żadna akcja front-end nie jest potrzebna.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/ChangeStatus?documentDefinitionId=3025&recordId=1&transitionId=3037' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{
    "StartDate": "2026-04-25",
    "EndDate": "2026-04-25",
    "ReservedBy": "adam",
    "Purpose": "test",
    "Attendees": 1,
    "IsRecurring": false,
    "Notes": "test"
  }'

GET /Document/GetDocumentAccessModel — uprawnienia użytkownika

Zwraca uprawnienia CRUD zalogowanego użytkownika do konkretnej instancji.

Wg stanu na wersję 1.15.6.4 nAxiom nie obsługuje uprawnień do tworzenia instancji dokumentów, stąd odpowiedź “canCreate”: false należy zignorować.

Parametr query Typ Wymagane Opis
recordId string tak ID instancji
documentId int nie ID dokumentu biznesowego

Odpowiedź 200 OK:

{
  "canCreate": false,
  "canRead":   true,
  "canUpdate": true,
  "canDelete": true
}

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/GetDocumentAccessModel?recordId=1&documentId=3025' \
  --header 'Authorization: Bearer <TOKEN>'

POST /Document/GetDataByGrid/{gridRowGuid} — dane gridu

Zwraca dane widoku siatki (grid) z paginacją, sortowaniem i filtrowaniem.

Parametr ścieżki Typ Opis
gridRowGuid Guid RowGuid definicji gridu z modułu administratora

Body:

{
  "skip": 0,
  "take": 50,
  "filters": [
    { "field": "ReservedBy", "operator": "eq",       "value": "adam" },
    { "field": "Attendees",  "operator": "gt",       "value": "1"    },
    { "field": "Purpose",    "operator": "contains", "value": "test" }
  ],
  "sort": [
    { "field": "Code", "dir": "desc" }
  ]
}

Operatory filtrowania: eq, neq, gt, gte, lt, lte, contains, doesnotcontain, startswith, endswith, isnull, isnotnull, isempty, isnotempty. Wiele filtrów łączonych jest operatorem AND (OR nie jest obsługiwane).

Kierunki sortowania: asc, desc.

Odpowiedź 200 OK:

{
  "gridMetadata": { "rowGuid": "...", "code": "...", "name": "..." },
  "totalRecords": 6,
  "data": [ { /* rekordy zgodne z definicją kolumn gridu */ } ]
}

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/GetDataByGrid/32f1e839-d446-40c6-8c00-f841f632d46e' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{ "skip": 0, "take": 50, "sort": [ { "field": "Code", "dir": "desc" } ] }'

POST /Document/CreateNewSchema — generowanie tabeli

Generuje nową tabelę SQL w bazie nAxiom oraz opcjonalnie powiązane elementy aplikacji (formularz, statusy, lista, autonumeracja). Endpoint wymaga uprawnienia systemowego Budowanie aplikacji.

Parametr query Typ Wymagane Opis
moduleDefinitionId int tak ID modułu, w którym ma powstać tabela

Body:

{
  "tableName": "NowaTabela",
  "tableSchema": "dbo",
  "tablePrefix": "PREF",
  "tableType": 1,                  // 0=Simple, 1=Business, 2=Catalog, 3=TableFunction, 4=System
  "pkName": "Id",
  "pkType": "int",
  "autoIncrement": true,
  "customFields": [
    { "name": "Name", "type": "varchar(100)", "isNullable": false }
  ],
  "runFlow": false,
  "generateDocumentType": false,
  "generateAutonumeration": false,
  "generateWorkflow": false,
  "generateForm": false,
  "generateRecordList": false
}

Odpowiedź 200 OK: true.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Document/CreateNewSchema?moduleDefinitionId=2' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{
    "tableName": "TestApiTable",
    "tableSchema": "dbo",
    "tablePrefix": "TEST",
    "tableType": 1,
    "pkName": "Id",
    "pkType": "int",
    "autoIncrement": true,
    "customFields": [ { "name": "Name", "type": "varchar(100)", "isNullable": false } ]
  }'

Endpointy formularzy (/Form)

GET /Form/GetBasicFormById — definicja formularza

Zwraca definicję formularza wraz z danymi instancji bez informacji o uprawnieniach do instancji. Jeżeli potrzebujesz dodatkowo flag CRUD, użyj POST /Document/GetFormById.

Parametr query Typ Wymagane Opis
id int tak ID definicji formularza
recordId string tak ID instancji dokumentu

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Form/GetBasicFormById?id=3024&recordId=1' \
  --header 'Authorization: Bearer <TOKEN>'

Endpointy załączników (/Attachment)

Wszystkie operacje wymagają, aby zalogowany użytkownik miał uprawnienia ACL do dokumentu, do którego należy załącznik.

POST /Attachment/UploadAttachment — dodanie załącznika

Dodaje plik jako nowy załącznik (overwrite=false) lub nadpisuje istniejący (overwrite=true). Plik przekazywany jest jako multipart/form-data w polu file.

Jeśli overwrite=true, ale nie ma załącznika do nadpisania, żądanie kończy się błędem 400 Api.AttachmentsModule.AttachmentNotFound.

Parametr query Typ Wymagane Opis
recordId string tak ID instancji dokumentu
businessDocumentId int tak ID dokumentu biznesowego
attachmentCategoryId int nie Pominięcie → kategoria domyślna definicji
overwrite bool tak true nadpisuje, false tworzy nową wersję

Odpowiedź 200 OK: AttachmentDto z id nowego załącznika, fileNameOriginal, fileSize, versionNumber, versioningIdentifier, rowGuid itd.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Attachment/UploadAttachment?recordId=14&businessDocumentId=3025&attachmentCategoryId=3025&overwrite=false' \
  --header 'Authorization: Bearer <TOKEN>' \
  --form 'file=@"C:/temp/upload-test.txt"'

GET /Attachment/GetAttachment — metadane załącznika

Parametr query Typ Wymagane
id int tak

Odpowiedź 200 OK: obiekt AttachmentDto z metadanymi (bez treści pliku).

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Attachment/GetAttachment?id=18' \
  --header 'Authorization: Bearer <TOKEN>'

GET /Attachment/DownloadAttachment — pobranie pliku

Zwraca strumień pliku z odpowiednim Content-Type i nagłówkiem Content-Disposition.

Parametr query Typ Wymagane
id int tak

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Attachment/DownloadAttachment?id=18' \
  --header 'Authorization: Bearer <TOKEN>' \
  --output downloaded.txt

DELETE /Attachment/RemoveAttachment — usunięcie załącznika

Usuwa załącznik wraz ze wszystkimi jego wersjami.

Parametr query Typ Wymagane
id int tak

Odpowiedź 200 OK: true. Po usunięciu GetAttachment?id=… zwróci HTTP 400 z kodem Api.AttachmentsModule.AttachmentNotFound.

Przykład:

curl -k --location --request DELETE 'https://naxiom.mojafirma.pl/publicapi/Attachment/RemoveAttachment?id=19' \
  --header 'Authorization: Bearer <TOKEN>'

Profile użytkowników (/User)

Wszystkie endpointy w tej grupie wymagają roli System - Administrator użytkowników PublicAPI oraz odpowiednich uprawnień PBA.

GET /User/GetById — odczyt profilu

Parametr query Typ Wymagane Opis
id string (GUID) tak ID użytkownika

Odpowiedź 200 OK: pełny UserProfileDto (login, e-mail, imię, nazwisko, daty, flagi internalApi, publicApi, mobileApi, role itd.).

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/User/GetById?id=3f53097e-bfe6-4690-e075-08d6ceba7d84' \
  --header 'Authorization: Bearer <TOKEN>'

POST /User/Save — utworzenie / modyfikacja

Tworzy nowego użytkownika (id=00000000-0000-0000-0000-000000000000) lub aktualizuje istniejącego. Aby nie zmieniać hasła, pomiń pole password lub ustaw jako wartość pusty ciąg.

Body: obiekt typu PublicApiUserProfile. Minimalny zestaw pól wymaganych do utworzenia:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "userName": "nowy.uzytkownik",
  "email": "nowy@example.com",
  "firstName": "Nowy",
  "lastName": "Użytkownik",
  "isActive": true,
  "expireDate": "2027-12-31T00:00:00",
  "isADUser": false,
  "internalApi": true,
  "publicApi": false,
  "mobileApi": false,
  "biometricVerification": false,
  "indefinitePassword": false,
  "userProfileRoles": [],
  "language": { "id": 1, "code": "pl", "name": "Polski", "active": true },
  "password": "<HASLO_UZYTKOWNIKA>"
}

Odpowiedź 200 OK: true przy sukcesie.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/User/Save' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{
    "id": "00000000-0000-0000-0000-000000000000",
    "userName": "nowy.uzytkownik",
    "email": "nowy@example.com",
    "firstName": "Nowy",
    "lastName": "Użytkownik",
    "isActive": true,
    "expireDate": "2027-12-31T00:00:00",
    "internalApi": true,
    "publicApi": false,
    "mobileApi": false,
    "userProfileRoles": [],
    "language": { "id": 1, "code": "pl", "name": "Polski", "active": true },
    "password": "<HASLO_UZYTKOWNIKA>"
  }'

POST /User/AddNewUser — dodanie nowego konta

Body identyczny jak w User/Save. Endpoint dedykowany jest tworzeniu nowego konta — przy próbie zapisu istniejącego loginu zwraca błąd „Użytkownik z loginem … już istnieje”. Wymaga uprawnienia PBA UserCreate oraz konfiguracji Management API jak w User/Save.

Przykład: identyczny jak /User/Save, zmień ścieżkę na /User/AddNewUser.

Uprawnienia menu (/Permission)

Wszystkie endpointy wymagają roli System - Administrator użytkowników PublicAPI oraz uprawnienia PBA Przegląd aplikacji w module AdminSPA.

Aby administrator mógł nadać użytkownikowi to ustawienie, musi mieć dostęp do gałęzi uprawnień Budowanie aplikacji. (Można włączyć, logując się na konto użytkownika superuser).

GET /Permission/GetAll — wszystkie pozycje menu

Zwraca listę wszystkich elementów menu zdefiniowanych w systemie (z polami id, code, name, routerLink, icon, parentId, moduleDefinitionId, applicationId, rowGuid itd.).

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Permission/GetAll' \
  --header 'Authorization: Bearer <TOKEN>'

GET /Permission/GetForRole — uprawnienia roli

Zwraca tablicę ID elementów menu, do których ma dostęp wskazana rola.

Parametr query Typ Wymagane
roleId int tak

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/Permission/GetForRole?roleId=1' \
  --header 'Authorization: Bearer <TOKEN>'

Zastępstwa (/PermissionDelegation)

Wszystkie endpointy wymagają roli System - Administrator użytkowników PublicAPI.

GET /PermissionDelegation/GetAllVisibleForMe — lista zastępstw

Zwraca zastępstwa widoczne dla zalogowanego użytkownika.

Parametr query Typ Wymagane Opis
takeActive bool tak true – tylko aktywne, false – tylko nieaktywne

Odpowiedź 200 OK: tablica obiektów z polami id, isActive, userFromId, userFromName, userForId, userForName, creationDate, dateFrom, dateTo, permittedRoles, permittedRolesInOrgUnits.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/PermissionDelegation/GetAllVisibleForMe?takeActive=true' \
  --header 'Authorization: Bearer <TOKEN>'

GET /PermissionDelegation/Get — szczegóły zastępstwa

Parametr query Typ Wymagane
id int tak

Odpowiedź 200 OK: pełen PermissionDelegationDto z zagnieżdżonymi profilami userFrom, userFor, creationUser, datami obowiązywania oraz flagą forwardEmailNotification.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/PermissionDelegation/Get?id=1' \
  --header 'Authorization: Bearer <TOKEN>'

POST /PermissionDelegation/Save — utworzenie / edycja zastępstwa

Body:

{
  "id": 0,
  "isActive": true,
  "userFromId": "<GUID użytkownika zastępowanego>",
  "userForId":  "<GUID użytkownika zastępującego>",
  "dateFrom":   "2027-01-01T00:00:00",
  "dateTo":     "2027-06-30T23:59:59",
  "forwardEmailNotification": true
}

id=0 — utworzenie nowego zastępstwa; id>0 — modyfikacja istniejącego.

Odpowiedź 200 OK: true.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/PermissionDelegation/Save' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{
    "id": 0,
    "isActive": true,
    "userFromId": "af7f976f-243d-4ce2-4fec-08de965d0c05",
    "userForId":  "3f53097e-bfe6-4690-e075-08d6ceba7d84",
    "dateFrom":   "2027-01-01T00:00:00",
    "dateTo":     "2027-06-30T23:59:59",
    "forwardEmailNotification": true
  }'

Struktura organizacyjna (/OrganizationStructure)

GET /OrganizationStructure/GetOrganizationList — lista jednostek

Płaska lista wszystkich jednostek organizacyjnych.

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/OrganizationStructure/GetOrganizationList' \
  --header 'Authorization: Bearer <TOKEN>'

GET /OrganizationStructure/GetOrganizationStructure — struktura

Zwraca jednostki z relacjami parentId/children, co pozwala odbudować hierarchię.

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/OrganizationStructure/GetOrganizationStructure' \
  --header 'Authorization: Bearer <TOKEN>'

GET /OrganizationStructure/GetOrganizationById — szczegóły jednostki

Parametr query Typ Wymagane
id int tak 
curl -k --location 'https://naxiom.mojafirma.pl/publicapi/OrganizationStructure/GetOrganizationById?id=2013' \
  --header 'Authorization: Bearer <TOKEN>'

Synchronizacja struktury (/StructureSynchronization)

Endpointy importują dane z systemów zewnętrznych (np. AD) do tabel pomocniczych nAxiom. Po zaimportowaniu danych z UserProfileList / OUInstanceList / OUInstanceUsersList należy uruchomić SynchronizeStructure, który przeniesie je do tabel produkcyjnych.

Hasła nie są przenoszone — uwierzytelnianie zaimportowanych kont musi być realizowane przez AD lub inny system zewnętrzny.

POST /StructureSynchronization/UserProfileList

Importuje listę profili użytkowników. Wymaga uprawnienia systemowego Wszystkie aplikacje (AllAppUsage).

Odpowiedź 200 OK: true. Pusty body {} jest akceptowany — endpoint zwróci true mimo braku rekordów do zaimportowania.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/StructureSynchronization/UserProfileList' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --data '{}'

Konfiguracja (/ConfigurationManager)

GET /ConfigurationManager/GetImportStatus — status importu konfiguracji

Zwraca status importu pliku konfiguracyjnego .nax.

Parametr query Typ Wymagane
configurationId int nie

Odpowiedź 200 OK: koperta *RequestResponse*. W szczególności pole *messages* może zawierać komunikat *Api.Shared.NoPermissions*, gdy brakuje uprawnień do tej operacji.

Przykład:

curl -k --location 'https://naxiom.mojafirma.pl/publicapi/ConfigurationManager/GetImportStatus?configurationId=1' \
  --header 'Authorization: Bearer <TOKEN>'

Typowe błędy i ich rozwiązanie

Kod HTTP Komunikat (errorMessage) Przyczyna i rozwiązanie
401 (brak ciała) Brak / nieprawidłowy / wygasły token. Wykonaj /connect/token ponownie.
403 (brak ciała) Brak ważnego TOTP w nagłówku, lub konto bez Dostęp do Public API.
400 Api.Public.InsufficientPermissions Brak roli System - Administrator użytkowników PublicAPI
400 Api.Shared.NoPermissions Brak uprawnienia systemowego (np. *[AllAppManagement](#wymagania-dotyczące-profilu-użytkownika-public-api
400 Api.BusinessModule.CouldNotAddRecord Nieprawidłowe lub niekompletne pola body w Save. Sprawdź wymagane kolumny przez GetSchema.
400 Api.AttachmentsModule.AttachmentNotFound Załącznik o podanym id nie istnieje (np. po RemoveAttachment).
400 Api.PermissionDelegation.NotFoundRecord Zastępstwo o podanym id nie istnieje.
400 Api.UserProfileModule.UnknownErrorOnAddingUserInAuth Błąd podczas tworzenia profilu.
400 Api.FormModule.NoFormWithGivenId Niewłaściwy parametr — w Document/Get należy podać ID definicji formularza, nie ID dokumentu biznesowego.

Lista zweryfikowanych endpointów

Niniejszy artykuł obejmuje wyłącznie endpointy potwierdzone testami na działającej instancji nAxiom (wersja 1.15.6.4):

Grupa Endpointy
Dokumenty GetSchema, Get, Save, CreateWithAttachments, GetFormById, GetStatus, GetTransitions, GetFormTransitions, ChangeStatus, GetDocumentAccessModel, GetDataByGrid, CreateNewSchema
Formularze Form/GetBasicFormById
Załączniki UploadAttachment, GetAttachment, DownloadAttachment, RemoveAttachment
Użytkownicy User/GetById, User/Save, User/AddNewUser
Uprawnienia menu Permission/GetAll, Permission/GetForRole
Zastępstwa PermissionDelegation/GetAllVisibleForMe, PermissionDelegation/Get, PermissionDelegation/Save
Struktura organizacyjna OrganizationStructure/GetOrganizationList, GetOrganizationStructure, GetOrganizationById
Synchronizacja StructureSynchronization/UserProfileList
Konfiguracja ConfigurationManager/GetImportStatus

  1. Administrator musi mieć dostęp do gałęzi Budowanie aplikacji włączony przez superusera, aby mógł nadać to uprawnienie. ↩

Copyright © 2025 OPTEAM SA. Theme Copyright © 2017-2020 Patrick Marsceill. Distributed by an MIT license.