Generowanie plików PDF i dokumentów Word przez API – 5 przykładów moich szablonów z Documentero

Pisałem już o Documentero, które pozwala na generowanie plików PDF i dokumentów Word z szablonów za pomocą API – na przykład z poziomu kodu, albo narzędzi No/Low Code klasy N8N czy Retool. Tym razem przykłady z moich własnych projektów, w których generuję naprawdę skomplikowane pliki.

Czy generowanie plików za pomocą API jest Ci potrzebne?

Budując aplikacje lub automatyzacje jest szansa, że potrzebujesz czasem wygenerować dokument Word czy PDF na podstawie struktury danych. Może to być umowa w formacie .docx, faktura w .pdf, protokół, właściwie cokolwiek.

Może masz te dane w Airtable, przetwarzasz je w N8N lub Retool albo po prostu piszesz kod w dowolnym języku i nie chcesz używać dodatkowej biblioteki tylko gotowej usługi online.

Na rynku jest kilka aplikacji SaaS tego typu, są też darmowe biblioteki lub gotowe aplikacje, które możesz trzymać na własnym serwerze jako np. kontener Docker. Ja jednak używam Documentero i na samym końcu wpisu wytłumaczę dlaczego.

Najpierw jednak kilka przykładów – jak możesz wykorzystać tego typu usługę.

Jak możesz wykorzystać generowanie plików i dokumentów za pomocą API?

Chcesz dla siebie (lub klientów) przygotować:

• Formularz generowania np. szablonu umowy, w którym klient (lub Ty) wprowadzasz potrzebne dane a następnie dostajesz plik z szablonem (wg Twojego wzoru),
• Automatyzację w N8N, Make czy Zapier, w której wyślesz dane JSON (np. dane klienta i pozycje zamówienia) a w odpowiedzi dostaniesz link do faktury, który wyślesz do kolejnego kroku automatyzacji (np. pobranie pliku i wysłanie mailem),
• Aplikację, w której będzie przycisk „Generuj dokument” wysyłający do API żądanie HTTP zawierające setki pól i struktur (również zagnieżdżonych) a w odpowiedzi użytkownik dostanie gotowy dokument (np. wielostronicowy protokół z tabelami i zdjęciami)

Jeśli te przykłady Cię zaciekawiły – czytaj dalej.

Jak wykorzystuję generowanie plików w moich projektach

Poniżej konkretne, z życia wzięte przypadki użycia. Dotyczą głównie 2 dokumentów – projektu umowy i protokołu przeglądu budowlanego. Jeden wykorzystuję dla siebie a drugi w aplikacji dla klienta, którą buduję (o tym w innej serii wpisów).

Przykład 1 – „Nagłówkowe” dane umowy

Najpierw najprostszy przykład. Formularz, w którym podajemy dane dotyczące umowy i na ich podstawie generujemy jej nagłówek.

Może to wyglądać tak jak na ekranie poniżej – jest to formularz zbudowany wprost w Documentero. Ja używam go tylko dla siebie, aby po rozmowie z klientem przygotować mu szybko projekt umowy na opiekę nad 1 lub wieloma stronami.

Zauważ, że w polu „Dający zlecenie – linia 1” celowo wprowadziłem jakiś tekst. Zazwyczaj zostawiam to pole wypełnione domyślnym ciągiem kropek i wypełnia je potem (już na dokumencie) klient.

Dane trafiają do Documentero, w którym mam wgrany szablon umowy, zawierający taki oto fragment:

Efekt jest łatwy do przewidzenia:

Przykład 2 – Podsumowanie listy (tabeli) z usługami

W tym samym formularzu i szablonie jest tabela usług, w której wyliczone są strony, kwota miesięcznej opłaty dla każdej z nich oraz suma. Formularz z poprzedniego punktu ma sekcję z powtarzalnymi sekcjami i polami do wypełnienia, przykładowo:

Następnie dane trafiają do szablonu umowy, w którym jest fragment:

Efekt wygląda tak:

Przykład 3 – Konwersja liczb na kwoty i obliczanie netto/brutto

W treści umowy, chcemy podać kwotę netto, jej słowną reprezentację albo kwotę za rok z góry (z upustem)? Nic prostszego, posługując się danymi z tabeli usług (poprzedni przykład) oraz funkcjami matematycznymi (mnożenie x10 miesięcy) czy specjalną funkcją inWords (zamiana liczb na słowa – dostępna w kilkunastu językach) dodajemy w szablonie fragment:

Efekt jest następujący:

Przykład 4 – Wiele zagnieżdżonych struktur/tabel z danymi

Na koniec wróćmy do przykładu tabeli z danymi, ale przypuśćmy że mamy dane zagnieżdżone. Tym razem przykład z aplikacji do generowania protokołów, która ma między innymi strukturę:

• Obiekt 1
  • sekcja 1
    • element 1
    • element 2
  • sekcja 2
    • element 1
    • element 2
• Obiekt 2
  • sekcja 1
    • element 1
    • …
  • …
• …

I tak dalej. W samej aplikacji wygląda to tak (dla użytkownika):

Następnie w aplikacji jest przycisk wysyłający dane je w formie JSON do API Documentero

Następnie korzystam z takiego (prostego) szablonu:

Aby na koniec otrzymać taki efekt:

Przykład 5 – Obrazy statyczne i dynamiczne oraz sekcje warunkowo ukryte

Na koniec kilka słów o obrazkach. Documentero pozwala wgrywać szablony z na stałe umieszczonymi obrazkami – na przykład logo naszej firmy czy faksymile na fakturze.

Możemy też dowolną sekcję dokumentu (w tym taką zawierającą obraz) wyświetlić w dokumencie warunkowo. Mój przypadek jest taki, że przesyła do protokołu zmienną z inicjałami inspektorów budowlanych. Jeśli jest w niej odpowiedni ciąg znaków w dokumencie zostanie pokazany skan uprawnień danego inspektora.

Jeśli chcemy przekazać przez API obraz do osadzenia w dokumencie musimy w JSON przesłać URL do publicznie dostępnego pliku a w szablonie osadzić go w postaci {%URL}. Znak % powoduje osadzenie odnośnika jako obrazu. W momencie wysłania danych do API link musi być publicznie dostępny.

W wypadku aplikacji, nad którymi mamy pełną kontrolę możemy na czas generowania posłużyć się jakimś rodzajem tokena uwierzytelniającego dodawanego do URL i ważnego na przykład minutę.

Dlaczego Documentero? Bo to polska perełka na rynku generatorów dokumentów

Documentero to polska usługa SaaS, którą możesz niedrogo nabyć w dożywotnim planie na AppSumo. Oznacza to, że płacąc raz, masz comiesięczny limit dokumentów jakie możesz wygenerować i – dopóki usługa istnieje – nie musisz płacić ponownie. Do dyspozycji są trzy poziomy różniące się limitami:

Nie polecam tej usługi tylko dla prowizji (link do AppSumo jest linkiem partnerskim). Jestem jej realnym fanem, bo używam jej codziennie budując rozwiązania dla siebie i klientów. Co więcej, jako jedna z nielicznych na AppSumo, nie ma ona ani jednej oceny poniżej maksymalnych 5 Taco. Świadczy to o jej dojrzałości i naprawdę wysokiej funkcjonalności.

Jest jeszcze jedna ważna cecha. Twórca usługi jest często dostępny na czacie i już kilkanaście razy pomógł mi z używaniem swojego generatora, czasem wręcz wdrażając pewne funkcje, o które pytałem.

Podsumowanie

Mam nadzieję, że przykłady jakie podałem pokazują jak potężnym narzędziem jest Documentero. Jego możliwości nie kończą się oczywiście na powyższych przykładach. Jeśli masz pytania – pisz śmiało w komentarzu!