POST /v1/generate

Generate PDF

Generate a PDF document from a template with dynamic data.

Overview

The generate endpoint creates a PDF document by merging a template with the provided data. The generated PDF is stored temporarily and a download URL is returned in the response.

Documents are available for download for 24 hours. After that, you will need to regenerate the document or store it in your own storage.

Endpoint

			
				POST https://api.shablonix.com/v1/generate
Content-Type: application/json
Authorization: Bearer tf_live_your_api_key

Request Body

Parameter	Type	Required	Description
`template_id`	string	Yes	The ID of the template to use for generation
`data`	object	Yes	Key-value pairs to populate template variables
`options`	object	No	PDF generation options (page size, margins, etc.)
`webhook_url`	string	No	URL to receive a webhook when generation completes
`filename`	string	No	Custom filename for the generated PDF

Options

The options object allows you to customize PDF generation:

Page Size

Value	Dimensions	Use Case
`letter`	8.5 x 11 inches	US standard (default)
`a4`	210 x 297 mm	International standard
`legal`	8.5 x 14 inches	Legal documents
`custom`	Custom width/height	Requires width & height

Orientation

Value	Description
`portrait`	Vertical orientation (default)
`landscape`	Horizontal orientation

Margins

Margins can be specified in inches, millimeters, or pixels:

			
				{
  "options": {
    "margins": {
      "top": "1in",
      "right": "0.75in",
      "bottom": "1in",
      "left": "0.75in"
    }
  }
}

You can also use a single value to set all margins: "margins": "1in"

Full Options Example

			
				{
  "template_id": "invoice_pro",
  "data": { ... },
  "options": {
    "page_size": "a4",
    "orientation": "portrait",
    "margins": {
      "top": "20mm",
      "right": "15mm",
      "bottom": "20mm",
      "left": "15mm"
    },
    "header": {
      "enabled": true,
      "height": "50px"
    },
    "footer": {
      "enabled": true,
      "height": "30px",
      "content": "Page {{page}} of {{pages}}"
    },
    "print_background": true,
    "scale": 1.0
  }
}

Response

A successful request returns a JSON object with the generated document details:

			
				{
  "id": "doc_7f3k9x2m1n",
  "object": "document",
  "status": "completed",
  "template_id": "tpl_invoice_basic",
  "pdf_url": "https://cdn.shablonix.com/docs/doc_7f3k9x2m1n.pdf",
  "pdf_size": 142857,
  "page_count": 2,
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-16T10:30:00Z",
  "metadata": {
    "render_time_ms": 234
  }
}

Field	Type	Description
`id`	string	Unique document identifier
`status`	string	completed, processing, or failed
`pdf_url`	string	URL to download the PDF (expires in 24h)
`pdf_size`	integer	File size in bytes
`page_count`	integer	Number of pages in the document
`expires_at`	string	ISO 8601 timestamp when URL expires

Code Examples

			
				curl -X POST https://api.shablonix.com/v1/generate \
  -H "Authorization: Bearer tf_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl_invoice_basic",
    "data": {
      "company_name": "Acme Corp",
      "invoice_number": "INV-2024-001",
      "date": "January 15, 2024",
      "due_date": "February 15, 2024",
      "customer": {
        "name": "John Smith",
        "email": "john@example.com",
        "address": "123 Main St, New York, NY 10001"
      },
      "items": [
        {
          "description": "Web Development Services",
          "quantity": 40,
          "unit_price": 150,
          "total": 6000
        },
        {
          "description": "UI/UX Design",
          "quantity": 20,
          "unit_price": 125,
          "total": 2500
        }
      ],
      "subtotal": 8500,
      "tax_rate": 8.5,
      "tax_amount": 722.50,
      "total": 9222.50
    },
    "options": {
      "page_size": "letter",
      "orientation": "portrait"
    }
  }'

Async Generation

For large documents or batch processing, use async generation by providing a webhook_url. The API returns immediately with a processing status, and your webhook receives the result when generation completes.

			
				{
  "template_id": "tpl_annual_report",
  "data": { ... },
  "webhook_url": "https://your-app.com/webhooks/shablonix"
}

The initial response will have status: "processing". See the Webhooks documentation for details on handling the completion callback.