Specyfikacja obiektów report i output (Formaty wejściowe oraz wyjściowe)

Opis mechanizmu

W sPrint API właściwości wejściowe pakietów szablonów (przekazywane w obiekcie report) oraz parametry zapisu dokumentów wynikowych (konfigurowane w obiekcie output) opierają się na strukturach polimorficznych. O tym, jaki zestaw pól zostanie poddany walidacji przez silnik renderujący, decyduje wartość nadrzędna przekazana w polu dataFormat.

Te uniwersalne komponenty wchodzą w skład struktur żądań dla kluczowych operacji API, takich jak sprawdzenie reportIds szablonu i jego podszablonów, synchroniczne generowanie raportów (szczegóły znajdziesz w dokumentacji POST /api/v0/Print czy asynchroniczne kolejkowanie zadań (POST /api/v0/PrintQueue/enqueue). Elastyczność polimorfizmu pozwala integratorom na swobodne mieszanie podejść – można przykładowo załadować plik szablonu z chmury S3, ale wymusić zwrot gotowego pliku PDF bezpośrednio w strumieniu odpowiedzi HTTP (Bytes).

 

Struktura obiektu „report” (Szablon wejściowy)

Właściwość report definiuje wejściowy plik projektu sPrint (.sp) i bazuje na modelu kontraktu FormattedSourceBaseViewModel. W zależności od zadeklarowanego trybu dostarczania danych, obiekt przyjmuje jedną z trzech poniższych struktur:

1. Wariant: Path (Wczytanie z dysku)

Używany w infrastrukturach on-premise lub sieciach lokalnych, gdzie serwer sPrint API posiada bezpośrednie uprawnienia dostępu do lokalnego bądź sieciowego systemu plików, na którym zdeponowane są pliki .sp.

"report": {
  "dataFormat": "Path",
  "path": "C:\\Ścieżka\\Do\\Pliku\\Raportu.sp"
}
  • dataFormat (string): Wartość stała "Path" wymuszająca walidację fizycznej lokalizacji pliku.
  • path (string): Pełna ścieżka bezwzględna wskazująca na strukturę pliku na dysku.

2. Wariant: Bytes (Bezpośredni przesył w formacie binarnym)

Dedykowany dla architektur rozproszonych i środowisk mikroserwisowych. Pozwala na przesłanie kompletnego pliku szablonu bezpośrednio w strukturze komunikatu JSON bez konieczności wcześniejszego zapisywania go na dysku.

"report": {
  "dataFormat": "Bytes",
  "source": "SGVsbG8gd29ybGQhSW50ZWdyYWNqYSBTY3JpbnQgQVBJIHYw..."
}
  • dataFormat (string): Wartość stała "Bytes" wymuszająca dekodowanie strumienia wejściowego.
  • source (string): Zawartość pliku binardnego szablonu .sp, przekonwertowana w całości do ciągu tekstowego Base64.

3. Wariant: S3 (Repozytorium Chmurowe)

Wskazuje silnikowi sPrint, że ma samodzielnie nawiązać połączenie i pobrać plik szablonu bezpośrednio z magazynu obiektowego chmury Amazon S3.

"report": {
  "dataFormat": "S3",
  "url": "https://s3.eu-central-1.amazonaws.com/bucket-erp/templates/invoice.sp"
}
  • dataFormat (string): Wartość stała "S3" wymuszająca walidację adresu URI repozytorium.
  • url (string): Pełny, bezpośredni publiczny bądź zabezpieczony tokenem adres URL obiektu przechowywanego w usłudze S3.

 

Struktura obiektu „output” (Zapis dokumentu wynikowego)

Właściwość output definiuje zachowanie silnika sPrint po pomyślnym zakończeniu renderowania pliku i bazuje na modelu FormattedOutputBaseViewModel. Obiekt steruje fizyczną dystrybucją wygenerowanego dokumentu (PDF, Excel, Word):

1. Wariant: Bytes (Strumień zwrotny)

Zmusza serwer do przetworzenia dokumentu w pamięci i odesłania go bezpośrednio w ciele odpowiedzi żądania synchronicznego jako plik binarny. Nie wymaga żadnych dodatkowych pól konfiguracyjnych.

"output": {
  "dataFormat": "Bytes"
}
  • dataFormat (string): Wartość stała "Bytes"
    API odsyła gotowy dokument w postaci binarnego strumienia bajtów. Zachowanie systemu zależy od wybranego endpointu żądania:

    • W przypadku synchronicznego /api/v0/Print: Silnik sPrint generuje dokument w pamięci RAM i zwraca go natychmiast, bezpośrednio w ciele tej samej odpowiedzi (Response Body) z kodem statusu 200 OK. Dane nie są nigdzie zapisywane po stronie serwera.
    • W przypadku asynchronicznego /api/v0/PrintQueue/enqueue: Procesor tła generuje plik i bezpiecznie buforuje jego bajty w magazynie kolejki (StoragePath). Po tym, jak zadanie osiągnie status „Succeeded”, plik należy jawnie pobrać osobnym żądaniem GET na endpoint /api/v0/PrintQueue/{operationId}/result.

2. Wariant: Path (Zapis na dysk serwera)

Wymusza na silniku sPrint zapisanie wyrenderowanego dokumentu bezpośrednio na udostępnioną przestrzeń dyskową serwera aplikacji.

"output": {
  "dataFormat": "Path",
  "path": "C:\\sPrint\\Outputs\\Faktura_Zaksięgowana.pdf"
}
  • dataFormat (string): Wartość stała "Path"Zwraca nagłówek HTTP 201 Created po udanej i trwałej alokacji pliku.
  • path (string): Docelowa, pełna ścieżka zapisu pliku na dysku serwera (musi być dostępna dla konta usługi serwera sPrint).

3. Wariant: S3 (Zapis bezpośrednio do magazynu chmurowego AWS)

Silnik sPrint po zakończeniu procesu renderowania automatycznie przesyła plik bezpośrednio do struktury Twojego zewnętrznego repozytorium S3 za pomocą mechanizmu przesyłania strumieniowego pliku.

"output": {
  "dataFormat": "S3",
  "url": "https://s3.eu-central-1.amazonaws.com/bucket-erp/archives/2026/doc.pdf"
}
  • dataFormat (string): Wartość stała "S3"Zwraca status HTTP 201 Created po poprawnym zakończeniu przesyłania obiektu.
  • url (string): Pełny adres URL umożliwiający silnikowi sPrint wgranie dokumentu chmurowego.

 

Realne Kompleksowe Przykłady (JSON Payload dla /api/v0/Print)

Poniższe kompletne struktury pokazują, jak w praktyce można łączyć polimorficzne właściwości obiektów report oraz output wewnątrz jednego zapytania biznesowego do sPrint API.

Przykład 1: report: Path -> output: Bytes

Scenariusz, w którym szablony są przechowywane w ustrukturyzowanym katalogu na dysku serwera aplikacji, a wygenerowany dokument wraca do aplikacji binarnie, ona go przetwarza i wyświetla go operatorowi na ekranie lub wysyła dalej w zależności od wdrożonej implementacji.

{
  "operationId": "print-action-001",
  "printFormat": "Pdf",
  "report": {
    "dataFormat": "Path",
    "path": "C:\\sPrint\\Templates\\FakturaSprzedazy.sp"
  },
  "output": {
    "dataFormat": "Bytes"
  }
}

Przykład 2: report: Bytes -> output: Bytes

Scenariusz w pełni bezdyskowy. Integrator pobiera szablon .sp z bazy danych systemu nadrzędnego, koduje go w Base64 i przesyła w żądaniu, oczekując zwrotnie gotowego strumienia dokumentu Excel bez dotykania systemu plików serwera.

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

Przykład 3: report: S3 -> output: S3

Zarówno pobranie bazowego szablonu .sp, jak i ostateczny eksport gotowego dokumentu PDF realizowany jest automatycznie na poziomie chmurowych zasobów AWS S3.

{
  "operationId": "print-action-003",
  "printFormat": "Pdf",
  "report": {
    "dataFormat": "S3",
    "url": "https://s3.eu-central-1.amazonaws.com/szablony-erp/faktura.sp"
  },
  "output": {
    "dataFormat": "S3",
    "url": "https://s3.eu-central-1.amazonaws.com/wydruki-erp/2026/FV_10_2026.pdf"
  }
}

Przykład 4: report: S3 -> output: Path

Scenariusz dedykowany dla rozproszonych środowisk hybrydowych. Szablon raportu pobierany jest centralnie z repozytorium chmurowego, ale ostateczny wydruk PDF zostaje trwale zapisany na dysku serwera lokalnego w archiwum plikowym firmy.

{
  "operationId": "print-action-004",
  "printFormat": "Pdf",
  "report": {
    "dataFormat": "S3",
    "url": "https://s3.eu-central-1.amazonaws.com/szablony-erp/faktura.sp"
  },
  "output": {
    "dataFormat": "Path",
    "path": "C:\\sPrint\\Outputs\\WygenerowanaFaktura.pdf"
  }
}

Czy ten artykuł był pomocny?

Wyślij opinie