Data streams

@TODO: Opisać sposób używania zmiennych w szablonach, opisać szablon typu file (dla PDF),

Strumień danych

Strumień danych to połączenie utworzonych szablonów dokumentów z typem danych. Umożliwia on sklasyfikowanie transakcji, czyli zbioru zdarzeń, jakie są obsługiwane w ramach serwisu zewnętrznego (np. sprzedaż). Każdy strumień danych może korzystać z jednego typu danych.

Użytkownik techniczny jest pośrednikiem pomiędzy zewnętrznym systemem a T-API. Posiada on certyfikat oraz klucz API wykorzystywany do szyfrowania danych oraz uwierzytelniania się w T-API (więcej informacji na temat autentykacji dostepnych jest w Authentication). Użytkownik techniczny przypisywany jest do strumienia danych. Każdy użytkownik techniczny może być przypisany do wielu strumieni danych.

Atrybut	Typ	Opis
Nazwa		składaja się z dużych liter, cyfr oraz podkreślników, nie może być dłuższa niz 36 znaków
Użytkownik Techniczny		ID użytkownika technicznego pobrane z kontekstu zapytania do API (URI)
Typ Danych		ID typu danych należący do organizacji użytkownika technicznego
Szablony		Musi zawierać conajmniej jeden szablon, może zawierać ich wiele
	ID Szablonu	ID szablonu należący do organizacji użytkownika technicznego. Każdy szablon może zostać przypisany tylko raz do jednego strumienia danych.
	Nazwa Dokumentu	Jest to pole typu string przyjmujące jeden lub więcej placeholder'ów %parameter.field%. Pole musi korzystać z pola header lub z tego samego parametru z którego korzysta szablon. *
	Referencja Dokumentu	Jest to pole typu string przyjmujące jeden lub więcej placeholder'ów %parameter.field%. Pole musi korzystać z pola header lub z tego samego parametru z którego korzysta szablon. *
	Zewnętrzne ID Dokumentu	Jest to pole typu string które referuje do pola parametru, z którego korzysta szablon. Na podstawie tego ID system jest w stanie zidentyfikować pojedyncze dokumenty utworzone na podstawie transakcji. *

* Parametrem jest tutaj obiekt z którego korzysta szablon, jeden szablon może mapować dane z jednego obiektu oraz header’a transakcji.

Kopiowanie strumienia danych

Wraz z utworzeniem transakcji, strumień danych jest do niej kopiowany. Dzięki temu możliwe jest modyfikowanie strumienia danych w odniesieniu do konkretnej transakcji, a nie tylko w ujęciu globalnym. Zmiany wprowadzone w strumieniu danych w danej transakcji, będą skutkować na transakcję po jej zaktualizowaniu.

Konfiguracja strumienia danych

Konfigurację strumienia danych można przeprowadzić za pomocą requestu POST wysyłanego do endpointa /api/v2/organisations/{organisationV2}/data-streams, gdzie {organisationV2} to id organizacji.

Payload przesyłanego żądania w przypadku konfiguracji strumienia danych ma następującą postać:

{
  "name": "string",
  "data_type": "string",
  "technical_user_id": 0,
  "templates": [
    {
      "template_id": 0,
      "template_name": "string",
      "document_name": "string",
      "document_reference": "string",
      "document_external_id": "string",
      "document_content": "string",
      "is_blocked": true
    }
  ],
  "valid_start": "2023-05-19T08:35:44.572Z",
  "valid_end": "2023-05-19T08:35:44.572Z"
}

Payload zawiera pola:

template_id - wskazującego identyfikator szablonu w systemie Pergamin,
template_name - nazwa szablonu dokumentu,
document_name - nazwa dokumentu tworzonego w ramach transakcji,
document_reference - referencję tworzonego dokumentu,
document_external_id - zewnętrzne id,
document_content - ścieżkę pobierania informacji na temat pliku PDF,
is_blocked - ustawienie zezwalające lub nie na późniejszą aktualizację dokumentu, który zostanie utworzony z danego szablonu.

Konfiguracja strumienia danych z plikiem PDF

T-API rozszerza możliwośći przesyłanych danych, z których automatycznie zostaną utworzone dokumenty. Oprócz danych do wcześniej utworzonych szablonów, T-API umożliwia przesyłanie plików PDF.

Plik PDF powinien być uwzględniony w strumieniu danych - konieczne jest wskazanie jego lokalizacji, czyli argumentu i pola, w którym będzie on przesyłany (np. headerItemFile). Poandto pole is_blocked musi przyjąć wartość true.

Przykładowy payload strumienia danych z uwzględnieniem przesyłanego pliku PDF:

{
  "name": "string",
  "data_type": "string",
  "technical_user_id": 0,
  "templates": [
    {
      "template_id": null,
      "template_name": null,
      "document_name": "PDF %headerTransactionId%",
      "document_reference": "%headerTransactionId%",
      "document_external_id": "PDF_%headerTransactionId%",
      "document_content": "headerItemFile",
      "is_blocked": true
    }
  ],
  "valid_start": "2023-05-19T08:35:44.572Z",
  "valid_end": "2023-05-19T08:35:44.572Z"
}