Renduva documentation

HTTP API

Renduva has one endpoint. Any language that can make an HTTP request can call it; the PL/SQL package is a thin client over the same call.

POST /generate

POST /generate
Authorization: Bearer <API key>
Content-Type: application/json

{
  "template": { "type": "docx", "source": "<base64 of the .docx file>" },
  "output":   { "type": "pdf", "filename": "bills_2026.pdf" },
  "data":     [ { "customer": "...", "items": [ ] }, { "customer": "...", "items": [ ] } ]
}

Field	Required	Meaning
`template`	yes	Either the name of a stored template as a plain string, e.g. `"invoice"`, or `{ "type", "source" }` with the file in base64
`output.type`	yes	`pdf` or `docx`
`output.filename`	no	File name given in `Content-Disposition`; default `document.<type>`
`data`	yes	One object (one document), or a list of objects (one document per record, merged into one PDF)

How tags and data values behave is described in Templates and tags.

Several records, one file

When data is a list, the template is filled once per record and the results are merged, in order, into one PDF: a month's invoices in one call, one invoice per page set. Each record starts on a new page, with its own headers, footers and page numbers. DOCX output takes a single record.

Success

200 OK. The body is the file itself, with Content-Type (e.g. application/pdf) and Content-Disposition: attachment; filename=....

Errors

The body is JSON: {"error": "<message>"}.

Status	When
400	The request is not valid JSON, a required field is missing, the base64 or the template name is invalid, or `data` is not an object or a list of objects
401	Missing or invalid API key
404	No stored template with that name
409	Two stored templates share a name (e.g. `invoice.docx` and `invoice.xlsx`)
413	The request is larger than the server's limit (50 MB by default)
422	The template could not be rendered: a tag error, an unsupported output type, or a failed conversion

Messages name the offending tag or field but never repeat data values.

Examples

curl, with a stored template:

curl -H "Authorization: Bearer $RENDUVA_KEY" \
     --data-binary @request.json \
     -o bills_2026.pdf \
     http://renduva.internal:8080/generate

Python, sending the template with the request:

import base64, requests

with open("invoice.docx", "rb") as f:
    template = base64.b64encode(f.read()).decode()

r = requests.post(
    "http://renduva.internal:8080/generate",
    headers={"Authorization": f"Bearer {key}"},
    json={"template": {"type": "docx", "source": template},
          "output": {"type": "pdf"},
          "data": {"customer": "City of Example", "items": []}},
)
r.raise_for_status()
open("invoice.pdf", "wb").write(r.content)