Opis mechanizmu

Tablica parameters to uniwersalny komponent struktury żądań sPrint API, wykorzystywany we wszystkich kluczowych endpointach systemu (zarówno synchronicznym POST /Print, jak i asynchronicznym kolejkowym POST /PrintQueue/enqueue). Obiekt ten odpowiada za dynamiczne wstrzykiwania lub nadpisywanie wartości zmiennych biznesowych bezpośrednio w silniku raportowym, tuż przed wykonaniem zapytań SQL i ostatecznym wyrenderowaniem dokumentu.

Zastosowanie tej struktury pozwala na pełną parametryzację wydruków (np. przekazywanie ID dokumentu, filtrów dat, czy flag sterujących wyglądem dokumentu) z poziomu kodu aplikacji integrującej, eliminując potrzebę fizycznej modyfikacji spakowanego szablonu .sp.

• Typ struktury: Array of Objects
• Wymagany: Nie (obiekt opcjonalny)
• Obsługiwane typy danych: Zależne od definicji zmiennej w szablonie. W strukturze JSON wszystkie wartości (Value) przekazywane są zawsze jako ciąg tekstowy (String), a silnik sPrint wewnętrznie rzutuje je na typy docelowe (np. Int64, Boolean, String, DateTime).

Właściwości obiektu (Parameter Object)

Każdy element wewnątrz tablicy parameters reprezentuje pojedynczą zmienną i musi zachować następującą strukturę:

{
  "name": "string",
  "value": "string"
}

• name (string): Wymagany. Dokładna nazwa parametru / zmiennej zadeklarowanej w zapytaniu SQL lub właściwościach szablonu (wielkość liter ma znaczenie, np. @id_dokumentu wymaga podania wartości id_dokumentu).
• value (string): Wymagany. Wartość przekazywana do silnika raportowego w formie ciągu tekstowego, niezależnie od docelowego typu danych zmiennej.

Struktura parametrów w odpowiedzi diagnostycznej (/Info)

Podczas wysyłania zapytania na endpoint POST /api/v0/Info, silnik sPrint API zwraca techniczną listę parametrów, mapując zmienne podszablonów za pomocą notacji kropkowej w polu key. Pozwala to deweloperowi na łatwą identyfikację zmiennych biznesowych ukrytych w podraportach:

{
  "rootGuid": "bac51d18-a4dc-47f7-828c-44e9500cc6ac",
  "parameters": [
    {
      "name": "id_dokumentu",
      "key": "id_dokumentu",
      "type": "Int64",
      "value": [ 0 ]
    },
    {
      "name": "czy_duplikat",
      "key": "czy_duplikat",
      "type": "Boolean",
      "value": [ false ]
    },
    {
      "name": "etykieta_kod_kreskowy",
      "key": "podszablon_logistyczny.etykieta_kod_kreskowy",
      "type": "String",
      "value": [ "00000000" ]
    }
  ]
}

Kompletny przykład struktury żądania (Payload JSON)

Poniższy produkcyjny payload obrazuje poprawne zdefiniowanie sekcji danych technicznych połączenia (data), wstrzyknięcie pełnej definicji bazy danych MS SQL systemu ERP (dataSources) odpowiadającej za zasilenie raportów oraz przekazanie kompletu parametrów biznesowych:

{
  "operationId": "wydruk-faktury-wz-2026",
  "printFormat": "Pdf",
  "report": {
    "source": "SGVsbG8gd29ybGQh...",
    "dataFormat": "Bytes"
  },
  "output": {
    "dataFormat": "Bytes"
  },
  "data": {
    "server": "jelcz",
    "key": "5000311484",
    "port": 5150,
    "type": "WebApi"
  },
  "dataSources": [
    {
      "name": "bazaOptima",
      "type": "Db",
      "dataSourceId": "718e6b85-e3a9-4490-b363-019e842cb342",
      "dbConnectionType": "MsSqlWindows",
      "server": "localhost",
      "databaseName": "CDN_Prezentacja_KH2025",
      "port": 1433
    }
  ],
  "parameters": [
    {
      "name": "id_dokumentu",
      "value": "10542"
    },
    {
      "name": "czy_duplikat",
      "value": "true"
    },
    {
      "name": "etykieta_kod_kreskowy",
      "value": "5901234567890"
    }
  ]
}