n8n utility endpoints¶

Routes under /api/v1/omni/n8n/* for automation helpers used by n8n workflows.

Authentication uses X-API-KEY (not JWT). Token resolution:

N8N_OMNI_API_TOKEN (preferred)
fallback: INTERNAL_API_SECRET

These routes are listed in PUBLIC_ENDPOINT_PREFIXES in main.py so the JWT middleware is skipped; each handler still enforces the API key via require_n8n_api_key.

Health¶

GET /n8n/health

Returns { "status": "ok", "service": "omni-n8n-utils" }.

HTML to PDF¶

POST /n8n/html-to-pdf

Render an HTML document to PDF. Uses WeasyPrint first, Playwright/Chromium as fallback.

Request body¶

{
  "html": "<html><body><h1>Report</h1></body></html>",
  "filename": "report.pdf",
  "page_format": "A4",
  "landscape": false,
  "print_background": true,
  "scale": 1.0,
  "response_format": "binary"
}

Field	Default	Notes
`html`	required	Full HTML document or fragment
`filename`	`document.pdf`	Used for `Content-Disposition`
`page_format`	`A4`	`A4`, `Letter`, or `Legal`
`landscape`	`false`	Landscape orientation
`print_background`	`true`	Playwright fallback only
`scale`	`1.0`	`0.1`–`2.0`, Playwright fallback only
`response_format`	`binary`	`binary` (PDF stream) or `base64` (JSON)

Responses¶

response_format=binary (default)

200 application/pdf
Header: Content-Disposition: attachment; filename="..."

response_format=base64

{
  "filename": "report.pdf",
  "content_type": "application/pdf",
  "size_bytes": 12345,
  "pdf_base64": "..."
}

Errors¶

401 — missing/invalid X-API-KEY
400 — empty HTML
500 — both PDF renderers failed

n8n example (HTTP Request node)¶

curl -X POST "http://service-omni:8007/api/v1/omni/n8n/html-to-pdf" \
  -H "X-API-KEY: $N8N_OMNI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"html":"<html><body><h1>Buchhaltung</h1></body></html>","filename":"report.pdf"}' \
  --output report.pdf

From n8n on the Docker network, use host http://service-omni:8007.

Implementation¶

Router: api/v1/endpoints/n8n_utils.py
PDF service: services/n8n/html_to_pdf.py
Auth helper: services/n8n/auth.py

Tests¶

backend/service_omni/app/tests/test_n8n_utils.py