Invoice Generator API Documentation

Overview

The Invoice Generator API allows you to create professional PDF invoices with support for multiple languages, RTL layouts, and various design templates. Built on Cloudflare Pages with serverless functions.

Key Features:

Multi-language support (English, Arabic, French, Spanish, etc.)
RTL (Right-to-Left) layout support
Multiple invoice templates
Real-time analytics tracking
Embedded fonts and assets

Authentication

Currently, the API uses public endpoints with optional admin authentication for analytics and administrative functions.

Note: For production use, consider implementing API keys or JWT tokens for sensitive operations.

Base URL

The base URL for all API endpoints depends on your deployment:

// Production
https://your-domain.pages.dev/api

// Development
http://localhost:8787/api
                    

Render PDF Endpoint

POST

/api/render

Generate a PDF invoice from JSON data. Returns the PDF file as binary data.

Request Body

Parameter	Type	Required	Description
layoutKey	string	Yes	Template layout (neat-pro, modern-right, classic-left, etc.)
lang	string	Yes	Language code (en, ar, ar-e, fr, es, etc.)
direction	string	No	Text direction (ltr or rtl)
meta	object	Yes	Invoice metadata
parties	object	Yes	From and to party information
items	array	Yes	Invoice line items
totals	object	No	Pre-calculated totals (optional)

Example Request

{ "layoutKey": "neat-pro", "lang": "en", "direction": "ltr", "meta": { "number": "INV-2024-001", "date": "2024-01-15", "currency": "USD", "logo": "data:image/png;base64,...", "notes": "Thank you for your business!" }, "parties": { "from_title": "Your Company Inc.", "from_details": "123 Business St.\nCity, State 12345\[email protected]", "bill_to": "Client Company\n456 Client Ave\nClient City, State 67890", "ship_to": "Same as billing address" }, "items": [ { "desc": "Web Design Services", "qty": 1, "price": 1500.00, "rowDisc": 0, "rowTax": 150.00 }, { "desc": "Hosting (12 months)", "qty": 12, "price": 50.00, "rowDisc": 60.00, "rowTax": 54.00 } ], "totals": { "subtotal": 2040.00, "taxTotal": 204.00, "discountTotal": 60.00, "total": 2184.00, "paid": 500.00, "due": 1684.00 }, "labels": { "invoice": "INVOICE", "lbl_bill_to": "BILL TO", "th_item": "Description", "th_qty": "Qty", "subtotal": "Subtotal" } }

Response

Content-Type: application/pdf

Headers: content-disposition: attachment; filename=invoice.pdf

Returns the generated PDF as binary data.

Analytics Endpoints

GET

/api/analytics/metrics

Get analytics metrics for invoice generation.

Response

{
  "totalRenders": 1542,
  "todayRenders": 23,
  "popularLayouts": [
    { "layout": "neat-pro", "count": 856 },
    { "layout": "modern-right", "count": 342 }
  ],
  "languageUsage": [
    { "language": "en", "count": 1200 },
    { "language": "ar", "count": 215 }
  ]
}
                            

POST

/api/analytics/track

Track custom analytics events.

Request Body

{
  "event": "custom_event",
  "data": {
    "layout": "neat-pro",
    "language": "en",
    "itemsCount": 5
  }
}
                        

Admin Endpoints

POST

/api/admin/auth

Admin authentication endpoint.

Request Body

{
  "username": "admin",
  "password": "secure_password"
}
                        

Available Layouts

The following invoice layouts are available:

Layout Key	Description	Features
`neat-pro`	Professional clean design	Modern, balanced layout
`modern-right`	Right-aligned modern design	Contemporary styling
`classic-left`	Traditional left-aligned	Classic business style
`elegant-gray-pro`	Elegant gray theme	Premium appearance
`band-blue-pro`	Blue band design	Colorful header band
`cool-waves-pro`	Wave pattern design	Creative background
`boxed-totals`	Boxed totals section	Highlighted totals area

Supported Languages

The API supports multiple languages with automatic RTL handling for Arabic:

Language Code	Language	Direction	Notes
`en`	English	LTR	Default language
`ar`	Arabic	RTL	Standard Arabic
`ar-e`	Eastern Arabic	RTL	Eastern Arabic numerals
`fr`	French	LTR	Français
`es`	Spanish	LTR	Español
`hi`	Hindi	LTR	हिन्दी
`pt`	Portuguese	LTR	Português

Code Examples

JavaScript Fetch Example

async function generateInvoice(invoiceData) {
    try {
        const response = await fetch('/api/render', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify(invoiceData)
        });
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        const blob = await response.blob();
        const url = URL.createObjectURL(blob);
        
        // Download the PDF
        const a = document.createElement('a');
        a.href = url;
        a.download = 'invoice.pdf';
        document.body.appendChild(a);
        a.click();
        document.body.removeChild(a);
        URL.revokeObjectURL(url);
        
    } catch (error) {
        console.error('Error generating invoice:', error);
    }
}

// Usage
const invoiceData = {
    layoutKey: 'neat-pro',
    lang: 'en',
    meta: {
        number: 'INV-001',
        date: '2024-01-15',
        currency: 'USD'
    },
    parties: {
        from_title: 'Your Company',
        bill_to: 'Client Name\nClient Address'
    },
    items: [
        { desc: 'Web Design', qty: 1, price: 1000 },
        { desc: 'Hosting', qty: 12, price: 50 }
    ]
};

generateInvoice(invoiceData);
                    

cURL Example

curl -X POST https://your-domain.pages.dev/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "layoutKey": "neat-pro",
    "lang": "en",
    "meta": {
      "number": "INV-001",
      "currency": "USD"
    },
    "parties": {
      "from_title": "Test Company",
      "bill_to": "Test Client"
    },
    "items": [
      {"desc": "Test Item", "qty": 1, "price": 100}
    ]
  }' \
  --output invoice.pdf
                    