Opis mechanizmu

Endpoint służy do pobierania pełnej struktury metadanych zaszytych wewnątrz pliku szablonu (.sp). Pozwala na bezinwazyjne „odpytanie” pliku o zdefiniowane parametry, zapytania SQL, źródła danych oraz unikalne identyfikatory (GUID) raportu głównego i podraportów.

Jest to kluczowy krok integracyjny, ponieważ uzyskane stąd identyfikatory reportId oraz dataSourceId są niezbędne do prawidłowego sterowania dynamicznymi zapytaniami w kolejnych endpointach (np. /Print lub /PrintQueue/enqueue).

• Wersja: v0
• Metoda HTTP: POST
• Format danych: application/json

Struktura żądania (Request Body)

{
  "operationId": "string",
  "data": {
    "server": "string",
    "key": "string",
    "port": 0,
    "type": "string",
    "sqlLogin": "string",
    "sqlPassword": "string"
   },
  "report": {
   "dataFormat": "string",
   "path": "string"
   }
}

• operationId (string): Wymagany. Unikalny identyfikator biznesowy operacji (np. GUID lub unikalny ciąg tekstowy), generowany przez system integrujący. Służy do śledzenia cyklu życia żądania.

data (object): sekcja odpowiedzialna za autoryzację żądania w menedżerze kluczy sPrint oraz definicję parametrów bramki dostępowej.

• server (string): Wymagany. Adres sieciowy IP lub nazwa domenowa serwera, na którym uruchomiona jest instancja menedżera licencji sPrint.
• key (string): Wymagany. Klucz licencyjny przypisany do danej instalacji lub partnera integracji, warunkujący dostęp do zasobów silnika renderującego.
• port (integer): Wymagany. Port sieciowy, na którym nasłuchuje usługa uwierzytelniająca (wartość liczbowa, np. 5150).
• type (string): Wymagany. Typ komunikacji i autoryzacji z menedżerem kluczy (np. wartość WebApi).
• sqlLogin (string): Opcjonalny. Login autoryzacyjny użytkownika używany w przypadku specyficznych połączeń bazodanowych przechodzących przez bramkę.
• sqlPassword (string): Opcjonalny. Hasło autoryzacyjne przypisane do konta zdefiniowanego w polu sqlLogin.

report (object): Sekcja definiująca format oraz fizyczną lokalizację wejściowego pliku szablonu z rozszerzeniem .sp, który ma zostać poddany analizie strukturalnej.

• dataFormat (string): Wymagany. Określa format, w jakim dostarczany jest plik szablonu do silnika sPrint. Przyjmuje wartości słownikowe, takie jak Bytes (dla strumienia zakodowanego w Base64) lub Path (dla fizycznej ścieżki dyskowej).
• source (string): Warunkowy. Zawiera pełny plik szablonu .sp przekonwertowany do surowego ciągu tekstowego Base64. Pole jest wymagane, jeżeli w parametrze dataFormat wybrano tryb Bytes.
• path (string): Warunkowy. Pełna ścieżka dostępu do pliku szablonu na dysku serwera (np. lokalna lub sieciowa ścieżka UNC). Pole jest wymagane, jeżeli w parametrze dataFormat wybrano tryb Path.
• url (string): Warunkowy. Zewnętrzny adres URL, pod którym silnik sPrint API może bezpośrednio pobrać plik szablonu. Używany w architekturach rozproszonych.

Kody odpowiedzi (Responses)

? HTTP 200 OK

Żądanie wykonane pomyślnie. Usługa sPrint API zwraca pełne mapowanie struktury technicznej dokumentu.

• Format odpowiedzi:

{
  "rootGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "parameters": [
    {
      "name": "string",
      "description": "string",
      "type": "string",
      "isMultiValue": true
    }
  ],
  "reports": [
    {
      "reportId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "query": "string",
      "dataSourceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "extraReportInfo": {
        "measureUnit": "HundredthsOfAnInch",
        "reportOrientation": "Vertical"
      }
    }
  ],
  "dataSources": [
    {
      "dataSourceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "description": "string"
    }
  ]
}

rootGuid (string): Główny, techniczny identyfikator szablonu raportu.

parameters (array): Lista parametrów wejściowych zdefiniowanych bezpośrednio w szablonie raportu (np. filtry, zakresy dat)

• name (string): Nazwa parametru użyta w definicji szablonu.

• description (string): Opis przeznaczenia danej zmiennej.

• type (string): Typ danych parametru (np. Integer, String, DateTime).

• isMultiValue (boolean): Określa, czy parametr przyjmuje pojedynczą wartość, czy tablicę danych (np. listę identyfikatorów).

reports (array): Lista wszystkich sekcji, tabel oraz podraportów wykrytych w pliku szablonu.

• reportId (string): Unikalny identyfikator GUID konkretnej sekcji raportu. Wartość ta jest kluczowa w kolejnych etapach integracji, ponieważ pozwala na precyzyjne wskazanie podsekcji, w której aplikacja kliencka chce dynamicznie nadpisać zapytanie SQL.

• name (string): Nazwa własna głównego szablonu nadana przez projektanta w Edytorze sPrint.

• query (string): Treść oryginalnego zapytania SQL, które zostało fabrycznie osadzone w danej sekcji szablonu.

• dataSourceId (string): Identyfikator bazy danych skojarzonej z zapytaniem dla tej konkretnej sekcji raportu.

• extraReportInfo.measureUnit (string): Jednostka miary układu szablonu (np. TenthsOfAMillimeter – dziesiąte części milimetra, lub HundredthsOfAnInch – setne części cala).

• extraReportInfo.reportOrientation (string): Orientacja strony wydruku dla danej sekcji (Vertical – pionowa, lub Horizontal – pozioma).

dataSources (array): Definicje oraz szczegółowe parametry połączeń bazodanowych zadeklarowanych wewnątrz szablonu.

• dataSourceId (string): Unikalny identyfikator GUID mapowania źródła danych.

• name (string): Nazwa techniczna połączenia w strukturze szablonu.

• description (string): Opcjonalny opis tekstowy źródła danych.

• type (string): Rodzaj źródła danych.

• server (string): Adres serwera bazy danych (host lub IP).

• port (integer): Port sieciowy usługi bazodanowej.

• connectionTimeout (integer): Maksymalny czas w sekundach oczekiwania na ustanowienie połączenia z bazą danych.

• commandTimeout (integer): Maksymalny czas w sekundach przeznaczony na wykonanie zapytania SQL przez silnik bazodanowy.

• serviceName (string/null): Nazwa dodatkowej usługi (wykorzystywana opcjonalnie przy wybranych silnikach bazodanowych).

• dbConnectionType (string): Techniczny typ połączenia oraz metoda uwierzytelniania zastosowana dla silnika bazy danych (np. MsSqlWindows dla autentykacji zintegrowanej).

• databaseName (string): Domyślna nazwa bazy danych, z którą łączy się szablon w celu pobrania danych.

? HTTP 401 Unauthorized

Brak autoryzacji. Przekazany klucz licencyjny Comarch jest nieprawidłowy, nieaktywny lub wygasł.

Format odpowiedzi: application/json (string)


? HTTP 422 Unprocessable Content

Błąd biznesowy przetwarzania szablonu (np. błąd ładowania pliku, niepoprawna ścieżka lub uszkodzona struktura pliku).

Format odpowiedzi:application/json (string)

Przykład wywołania:

Żądanie:

{
 "operationId": "info-test-guid-2026",
 "data": {
 "server": "jelcz",
 "port": 5150,
 "key": "5000311484",
 "type": "WebApi"
},
 "report": {
  "dataFormat": "Path",
  "path": "C:\\sPrintSzablony\\szablon.sp"
 }
}

Odpowiedź:

{
  "rootGuid": "bf1fca04-e53e-4000-88d9-108f51e1596a",
  "parameters": [],
  "reports": [
    {
      "reportId": "bf1fca04-e53e-4000-88d9-108f51e1596a",
      "name": "glowny_szablon",
      "query": "select top 10 * from cdn.tranag where\ntrn_gidtyp = 2033 and trn_gidnumer = 165",
      "dataSourceId": "665883ba-bc29-47a7-9d96-019e6926c4d5",
      "extraReportInfo": {
        "measureUnit": "TenthsOfAMillimeter",
        "reportOrientation": "Vertical"
      }
    },
    {
      "reportId": "862f5203-159f-4fff-99f1-eeaf9dbdcc96",
      "name": "podszablon",
      "query": "select * from cdn.traelem\nwhere tre_gidtyp = @gidtyp and tre_gidnumer = @gidnumer",
      "dataSourceId": "665883ba-bc29-47a7-9d96-019e6926c4d5",
      "extraReportInfo": {
        "measureUnit": "TenthsOfAMillimeter",
        "reportOrientation": "Vertical"
      }
    }
  ],
  "dataSources": [
    {
      "server": "localhost",
      "port": 1433,
      "connectionTimeout": 5,
      "commandTimeout": 600,
      "serviceName": null,
      "dbConnectionType": "MsSqlWindows",
      "databaseName": "KB_PROGRESS_FR_2026",
      "dataSourceId": "665883ba-bc29-47a7-9d96-019e6926c4d5",
      "name": "BazaXLProdukcyjna",
      "description": "",
      "type": "Db"
    }
  ]
}