Opis mechanizmu

Endpoint służy do asynchronicznego zlecania generowania (renderowania) gotowych dokumentów do kolejki zadań w tle (zarządzanej przez system Hangfire) na podstawie szablonów sPrint (.sp) oraz dynamicznie przekazywanych danych. Działa w sposób nieblokujący – zamiast czekać na zakończenie procesu tworzenia pliku, natychmiast rejestruje zadanie i zwraca jego unikalne identyfikatory, co pozwala na obsługę ciężkich i masowych wydruków bez ryzyka zerwania timeoutu połączenia.

Struktura żądania wejściowego (Request Body) jest w 100% kompatybilna z kontrolerem synchronicznym. Silnik pozwala na pełne nadpisanie parametrów szablonu, zmianę zapytań SQL oraz dynamiczne przepięcie źródeł danych w locie (zarówno dla raportu głównego, jak i wybranych podszablonów). Wygenerowany asynchronicznie plik (w formacie PDF, XLS, XLSX lub DOCX) zostanie odłożony w lokalizacji plikowej/chmurowej bądź – w przypadku konfiguracji typu Bytes – zapamiętany w bazie danych do momentu jego jawnego pobrania dedykowanym endpointem wynikowym.

• 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). W architekturze kolejki jest wysoce zalecany – staje się kluczem biznesowym, za pomocą którego pobiera się gotowy plik z endpointu wynikowego.
• 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 kolejki.
• output (object): Kontener wymagany. Określa fizyczny sposób dystrybucji oraz format zapisu gotowego dokumentu po przetworzeniu zadania w tle. Zachowanie systemu zależy od wybranego trybu wyjściowego:
  • • Scenariusz 1 (dataFormat: „Bytes”): Procesor tła generuje plik i bezpiecznie buforuje jego bajty w StoragePath. Po tym, jak zadanie osiągnie status „Succeeded” co jest możliwe do sprawdzenia za pomocą endpointu GET /api/v0/PrintQueue/{jobId}/status plik należy jawnie pobrać osobnym żądaniem GET /api/v0/PrintQueue/{operationId}/result
    • Scenariusz 2 (dataFormat: „Path” lub „S3”): Proces tła automatycznie zapisuje gotowy plik bezpośrednio na wskazanym dysku serwera lub wysyła go do chmury Amazon S3. Gdy zadanie osiągnie status „Succeeded”, plik jest od razu gotowy do użycia w docelowym miejscu.
• dataSources (array): Tablica opcjonalna. Pozwala na dynamiczne nadpisywanie ciągów połączeń bazodanowych i zapytań na czas asynchronicznego generowania dokumentu.
• parameters (array): Tablica opcjonalna. Służy do wstrzykiwania wartości pod zmiennes zadeklarowane bezpośrednio w strukturze raportu.

Kody odpowiedzi (Responses)

? HTTP 202 Accepted

Zadanie wydruku zostało pomyślnie zwalidowane strukturalnie i umieszczone w kolejce przetwarzania Hangfire. W ciele odpowiedzi serwer zwraca unikalny identyfikator zadania (jobId) służący do monitorowania stanu oraz identyfikator powiązany z plikiem wynikowym (operationId).

Format odpowiedzi:

{
  "jobId": "hangfire-job-id-12345",
  "operationId": "my-operation-guid-123"
}

? 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, moduł kolejki asynchronicznej (Feature Flag) jest wyłączony w konfiguracji systemowej sPrint, lub zapytania zdefiniowane w dataSources zawierają błędy składniowe.

Format odpowiedzi: application/json (string)

Realne Kompleksowe Przykłady (JSON Payload)

Przykład 1: Zlecenie do kolejki z buforowaniem bajtów (Odbiór asynchroniczny przez /result)

Najbardziej powszechny scenariusz dla kolejki: serwer przyjmuje zadanie, renderuje plik w tle i bezpiecznie buforuje jego bajty w bazie danych. Po zakończeniu zadania (status Succeeded), dokument pobiera się dedykowanym endpointem GET.

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

Przykład 2: Kolejkowanie operacji opartej o dane binarne (report: Bytes -> output: Bytes)

Scenariusz asynchroniczny dla architektur chmurowych. Zarówno szablon wejściowy przekazywany jest jako ciąg Base64, jak i proces tła odłoży wygenerowany plik Excel (Xlsx) bezpośrednio w pamięci bazy kolejki do późniejszego odebrania.

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

Przykład 3: Ciężki raport w tle z nadpisaniem bazy danych i zapisem na dysk sieciowy (report: Path -> output: Path)

Zadanie zostaje wrzucone do kolejki Hangfire, dzięki czemu serwer od razu zwalnia wątek HTTP. W tle procesor pobiera szablon, przepina się na produkcyjny serwer SQL i trwale zapisuje gotowy plik PDF w strukturze katalogów sieciowych firmy.

{
  "operationId": "asynch-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!"
      }
    }
  ]
}