Dokumentacja REST API, CLI i Standardu WCAG / PDF-UA

Silnik pozwala na konwersję kodu HTML do dokumentów PDF zgodnych ze standardem PDF/UA-1 (ISO 14289-1) oraz wytycznymi WCAG 2.1 AA. Poniżej znajduje się pełny opis endpointów REST API, narzędzia wiersza poleceń oraz reguł CSS Paged Media.

1. Punkty Końcowe REST API (/api/v1)
POST /api/v1/render — Renderowanie kodu HTML do formatu PDF

Przyjmuje obiekt JSON lub formularz multipart. Zwraca strumień binarny PDF lub obiekt JSON z base64 i raportem audytu.

Przykładowe żądanie cURL:
curl -X POST http://10.8.0.5:5563/api/v1/render \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html lang=\"pl\"><head><title>Raport</title></head><body><h1>Raport Oficjalny</h1><p>Przykładowa treść.</p></body></html>",
    "title": "Raport Oficjalny",
    "author": "Jan Kowalski",
    "lang": "pl-PL",
    "size": "A4",
    "orientation": "portrait"
  }' \
  --output dokument.pdf
Przykład w Pythonie (requests):
import requests

url = "http://10.8.0.5:5563/api/v1/render"
payload = {
    "html": "<html lang='pl'><head><title>Faktura</title></head><body><h1>Faktura</h1></body></html>",
    "title": "Faktura",
    "format": "pdf"
}
r = requests.post(url, json=payload)
with open("wynik.pdf", "wb") as f:
    f.write(r.content)
POST /api/v1/render-template — Renderowanie wbudowanego szablonu z danymi JSON

Dostępne szablony: accessible_report, invoice, scientific_paper, official_certificate, product_catalog.

Przykładowe żądanie cURL:
curl -X POST http://10.8.0.5:5563/api/v1/render-template \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "invoice",
    "data": {
      "invoice_number": "FV/AUTO/01",
      "total_gross": 15990.00
    }
  }' \
  --output faktura.pdf
POST /api/v1/validate — Audyt dostępności WCAG kodu HTML lub pliku PDF

Zwraca ocenę punktową (0-100%), listę błędów i wskazówki naprawcze.

curl -X POST http://10.8.0.5:5563/api/v1/validate \
  -H "Content-Type: application/json" \
  -d '{"html": "<html><body><img src=\"test.jpg\"></body></html>"}'
GET /api/v1/health — Sprawdzenie statusu serwera (Healthcheck) 
curl http://10.8.0.5:5563/api/v1/health
# Odpowiedź: {"status":"healthy","version":"2.0.0","engine":"WeasyPrint + PDF/UA-1 Engine"}
2. Narzędzie Wiersza Poleceń (CLI / Bash)

Narzędzie cli.py umożliwia generowanie i weryfikację dokumentów bezpośrednio z konsoli oraz skryptów powłoki:

Polecenie Bash Opis
python3 cli.py convert -i input.html -o out.pdf --audit Konwersja pliku HTML do PDF/UA z audytem WCAG.
cat input.html | python3 cli.py convert - -o out.pdf Konwersja strumieniowa ze standardowego wejścia (potok / pipe).
python3 cli.py render-template -t invoice -d data.json -o faktura.pdf Generowanie PDF z wbudowanego szablonu i danych JSON.
python3 cli.py list-templates Wyświetlenie listy dostępnych szablonów.
python3 cli.py inspect-pdf dokument.pdf Inspekcja struktury tagów /StructTreeRoot i metadanych.
python3 cli.py validate input.html Walidacja reguł WCAG w pliku HTML.
3. Standardy Dostępności WCAG 2.1 AA & CSS Paged Media
Wymogi WCAG w pliku PDF:
  • Język dokumentu: <html lang="pl"> → /Catalog /Lang (pl-PL).
  • Tytuł: <title> w HTML → flaga DisplayDocTitle: true.
  • Nagłówki: Dokładnie jeden <h1>, logiczna kolejność bez przeskoków.
  • Ryciny: Atrybut alt="..." dla grafik lub role="presentation" dla ozdobników.
  • Tabele: Komórki nagłówkowe <th scope="col|row"> oraz podpis <caption>.
CSS Paged Media:
  • Paginacja: @page { @bottom-right { content: "Strona " counter(page) " z " counter(pages); } }
  • Okładka bez nagłówków: @page:first { @top-left { content: normal; } }
  • Zapobieganie rozcinaniu: table tr, figure, .card { break-inside: avoid; }
  • Powtarzanie nagłówka tabeli: thead { display: table-header-group; }