Opis mechanizmu

Endpoint służy do synchronicznego (natychmiastowego) generowania dokumentów na podstawie przesłanych szablonów sPrint oraz dynamicznie dostarczanych danych zasilających. Połączenie HTTP pozostaje otwarte przez cały czas trwania procesu renderowania. Po zakończeniu pracy, silnik sPrint zwraca gotowy dokument bezpośrednio w ciele tej samej odpowiedzi.

Struktura żądania pozwala na elastyczne sterowanie procesem: od wstrzykiwania pojedynczych parametrów biznesowych, przez całkowitą zmianę konfiguracji licencjonowania serwera, aż po dynamiczne przepinanie zapytań SQL oraz całych silników bazodanowych w locie. Wygenerowany plik może zostać przekazany bezpośrednio do aplikacji klienckiej jako surowy strumień bajtów lub trwale odłożony w zadeklarowanym magazynie plikowym serwera bądź chmury S3.

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

Struktura żądania (Request Body)

Model wejściowy payloadu JSON składa się z następujących sekcji głównych pierwszego poziomu:

{
  "operationId": "string",
  "printFormat": "string",
  "data": {},
  "report": {},
  "output": {},
  "dataSources": [],
  "parameters": []
}

• operationId (string): Opcjonalny, unikalny identyfikator danej operacji wydruku (np. GUID). Służy do celów diagnostycznych oraz ułatwia śledzenie i filtrowanie konkretnego wywołania w logach systemowych serwera.
• printFormat (string): Definiuje docelowy format wyjściowy pliku. Przyjmuje wartości z zamkniętego słownika Enum: "Pdf", "Xls", "Xlsx", "Docx"
• data (object): Kontener opcjonalny. Zawiera poświadczenia licencyjne serwera Comarch dla tego konkretnego wywołania.
• report (object): Kontener wymagany. Definiuje plik wejściowy szablonu sPrint (.sp) oraz metodę jego dostarczenia do silnika.
• output (object): Kontener wymagany. Określa fizyczny sposób dystrybucji oraz format zapisu gotowego dokumentu.
• dataSources (array): Tablica opcjonalna. Pozwala na dynamiczne nadpisywanie ciągów połączeń bazodanowych i zapytań na czas generowania dokumentu.
• parameters (array): Tablica opcjonalna. Służy do wstrzykiwania wartości pod zmienne zadeklarowane bezpośrednio w strukturze raportu.

Kody odpowiedzi (Responses)

? HTTP 200 OK

Zwracany wyłącznie wtedy, gdy w obiekcie wyjściowym wybrano opcję "dataFormat": "Bytes"Serwer odsyła wygenerowany plik w locie, jako binarny strumień danych.

Nagłówek:Content-Type odpowiedzi jest automatycznie dopasowywany do wybranego parametru printFormat  (np.  application/pdf)

Format odpowiedzi:

Surowy strumień bajtów pliku dokumentu (Binary Stream).

? HTTP 201 Created

Zwracany w sytuacji, gdy w obiekcie wyjściowym wybrano opcję "dataFormat": "Path" lub "dataFormat": "S3"Oznacza, że silnik pomyślnie wyrenderował dokument i trwale zapisał go w zadeklarowanej lokalizacji dyskowej lub chmurowej.

Format odpowiedzi: Brak zawartości (Empty Body).

? HTTP 401 Unauthorized

Brak uprawnień. Dynamiczna walidacja licencji przekazanej w obiekcie „data” zakończyła się niepowodzeniem lub globalny token licencyjny serwera sPrint utracił ważność.

Format odpowiedzi: application/json (string)

? HTTP 422 Unprocessable Content

Błąd przetwarzania logiki biznesowej. Występuje, gdy model JSON jest niepoprawny strukturalnie, wskazany plik szablonu .sp nie istnieje, jest uszkodzony lub zapytania zdefiniowane w dataSources zawierają błędy składniowe uniemożliwiające pobranie danych.

Format odpowiedzi: application/json (string)

Realne Kompleksowe Przykłady (JSON Payload)

Przykład 1: Generowanie PDF w locie (report: Path -> output: Bytes)

Najbardziej powszechny scenariusz: serwer pobiera plik szablonu z lokalnego dysku, przetwarza dane i natychmiast zwraca gotowy dokument PDF bezpośrednio w strumieniu odpowiedzi HTTP (Status 200 OK).

{
  "operationId": "synch-print-001",
  "printFormat": "Pdf",
  "report": {
    "dataFormat": "Path",
    "path": "C:\\sPrint\\Templates\\FakturaSprzedazy.sp"
  },
  "output": {
    "dataFormat": "Bytes"
  },
  "parameters": [
    {
      "name": "GidNumer",
      "value": "14255"
    }
  ]
}

Przykład 2: Pełna operacja In-Memory (report: Bytes -> output: Bytes)

Scenariusz bezdyskowy dla architektur chmurowych. Zarówno szablon wejściowy przesyłany jest jako ciąg Base64, jak i gotowy plik wynikowy Excel (Xlsx) wraca w ciele odpowiedzi HTTP (Status 200 OK).

{
  "operationId": "synch-print-002",
  "printFormat": "Xlsx",
  "report": {
    "dataFormat": "Bytes",
    "source": "SGVsbG8gd29ybGQhSW50ZWdyYWNqYSBTY3JpbnQgQVBJIHYw"
  },
  "output": {
    "dataFormat": "Bytes"
  }
}

Przykład 3: Wydruk z dynamicznym nadpisaniem bazy danych i zapisem na dysk serwera (report: Path -> output: Path)

Silnik sPrint pobiera szablon lokalny, ale na czas generowania raportu przepina się na produkcyjny serwer SQL klienta przy użyciu sekcji dataSources. Gotowy dokument zostaje trwale odłożony w archiwum plikowym serwera (Status 201 Created).

{
  "operationId": "synch-print-003",
  "printFormat": "Pdf",
  "report": {
    "dataFormat": "Path",
    "path": "C:\\sPrint\\Templates\\RaportZyskow.sp"
  },
  "output": {
    "dataFormat": "Path",
    "path": "D:\\Archiwum\\2026\\Raport_Finansowy.pdf"
  },
  "dataSources": [
    {
      "type": "Db",
      "reportIds": [],
      "server": "sql-prod-cluster",
      "connectionType": "MsSql",
      "databaseName": "CDN_Produkcja",
      "query": "SELECT * FROM cdn.KontaKsiegowe WHERE Rok = 2026",
      "credentials": {
        "login": "sprint_reader",
        "password": "UserPassword2026!"
      }
    }
  ]
}