Finvo API Documentation

Overview

What the Finvo API does

The Finvo API generates professional PDF invoices from structured data. You send invoice details as JSON, and we return a PDF ready to send to your clients.

Who it is for

The API is designed for:

• SaaS products that need to bill customers programmatically
• Solo founders automating their invoicing workflow
• Freelancers integrating invoicing into their tools
• Businesses that want invoice generation without building PDF infrastructure

What it does NOT do

• No invoice storage - PDFs are generated on-demand and streamed to you. We don't store them.
• No payment processing - Finvo generates invoices, but doesn't handle actual payments.
• No accounting integrations - The API is focused on PDF generation only.
• No invoice templates - The PDF layout is standardized (custom templates available on request).

Authentication

What an API key is

An API key is a secret token that identifies your Finvo account when making API requests. It works like a password for automated systems.

Where to find it

1. Log in to your Finvo dashboard
2. Navigate to the API Keys page
3. Click Generate New Key
4. Copy the key immediately - it's only shown once

Your API key will look like this:

finvo_sk_1a2b3c4d5e6f7g8h9i0j

How to include it in requests

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer finvo_sk_1a2b3c4d5e6f7g8h9i0j

Making Your First Request

Base URL

All API requests are made to:

POST https://https://finvo.dev/generate

Required headers

Every request must include:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Simple curl example

Here's a minimal request that will generate an invoice:

curl -X POST https://https://finvo.dev/generate \
  -H "Authorization: Bearer finvo_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-001",
    "date": "2026-01-19",
    "due_date": "2026-02-19",
    "sender": {
      "name": "Your Business Name",
      "email": "you@yourbusiness.com"
    },
    "bill_to": {
      "name": "Client Name",
      "email": "client@example.com"
    },
    "items": [
      {
        "description": "Consulting services",
        "quantity": 1,
        "rate": 1000.00,
        "amount": 1000.00
      }
    ]
  }' \
  --output invoice.pdf

If successful, you'll have a PDF file named invoice.pdf in your current directory.

Generating an Invoice

Required fields

Every invoice must include:

• invoice_number (string) - A unique identifier for this invoice
• date (string) - Invoice date in YYYY-MM-DD format
• due_date (string) - Payment due date in YYYY-MM-DD format
• sender.name (string) - Your business or personal name
• sender.email (string) - Your contact email
• bill_to.name (string) - Client or customer name
• bill_to.email (string) - Client contact email
• items (array) - At least one line item

Each line item requires:

• description (string) - What you're billing for
• quantity (integer) - How many units (must be > 0)
• rate (number) - Price per unit
• amount (number) - Total for this line (quantity × rate)

Optional fields

You can also include sender/bill_to address fields (address, city, state, zip) and notes.

Example (JavaScript)

async function generateInvoice() {
  const response = await fetch('https://https://finvo.dev/generate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer finvo_sk_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      invoice_number: 'INV-001',
      date: '2026-01-19',
      due_date: '2026-02-19',
      sender: {
        name: 'Your Company',
        email: 'you@company.com'
      },
      bill_to: {
        name: 'Client Name',
        email: 'client@example.com'
      },
      items: [{
        description: 'Web development',
        quantity: 1,
        rate: 5000.00,
        amount: 5000.00
      }]
    })
  });

  if (response.ok) {
    const buffer = await response.arrayBuffer();
    // Save or process the PDF
  }
}

Error Handling

Common HTTP status codes

Debugging checklist

1. Check the status code - tells you the category of error
2. Read the error message - it usually explains exactly what's wrong
3. Verify your API key - make sure it's copied correctly without extra spaces
4. Validate your JSON - use a JSON validator to catch syntax errors
5. Test with curl first - eliminates issues with your code/libraries
6. Check required fields - ensure all necessary fields are present

Usage Notes & Best Practices

Retrying failed requests

The API is stateless and safe to retry. Network timeouts and 500 errors are safe to retry immediately. For 429 (rate limit) errors, wait 60 seconds before retrying.

Keeping API keys secure

Do:

• Store API keys in environment variables, not in code
• Use different keys for development, staging, and production
• Rotate keys periodically (every 3-6 months)
• Revoke keys immediately if compromised

Don't:

• Commit API keys to Git or public repositories
• Share keys in Slack, email, or documentation
• Use production keys for testing
• Expose keys in client-side JavaScript

Limits & Expectations

Plan-based limits

If you hit your monthly limit, API requests will return 403 Forbidden. You can upgrade your plan to increase the limit immediately, or wait until your limit resets on the first day of each month.

Performance expectations

• Average response time: 200-500ms
• PDF size: Typically 30-100 KB depending on line items
• Timeout recommendation: Set client timeouts to 30 seconds