Skip to main content
This guide walks you through processing your first invoice with Invoice OCR. You’ll upload a document, extract structured data, and view the reconciliation results.

​
Before You Begin

You’ll need:
  • An OpenRouter API key (get one at openrouter.ai/keys)
  • Node.js 20+ installed
  • A sample invoice image or PDF for testing
OpenRouter provides access to multiple vision models including Gemini 2.5 Flash (recommended), GPT-4o Mini, and others. Your API key works with all models.

​
Step 1: Configure Your API Key

First, create your environment configuration file: 
cp .env.example .env.local
Then add your OpenRouter API key to .env.local:
.env.local
OPENROUTER_API_KEY=your_key_here
Never commit .env.local to version control. This file is gitignored by default and should contain secrets only.

​
Optional Configuration

You can customize model selection and PDF processing:
.env.local
OPENROUTER_API_KEY=your_key_here

# Model selection (default: google/gemini-2.0-flash if unset)
OPENROUTER_MODEL=openai/gpt-4o-mini

# PDF parsing engine (default: pdf-text)
OPENROUTER_PDF_ENGINE=pdf-text

# Optional: OpenRouter headers
OPENROUTER_SITE_URL=http://localhost:3000
OPENROUTER_APP_NAME=Invoice OCR
Available PDF engines:
  • pdf-text - Fast text extraction (recommended)
  • mistral-ocr - OCR-based extraction for scanned PDFs
  • native - Native PDF rendering

​
Step 2: Start the Development Server

Launch the application: 
npm run dev
The application will start at http://localhost:3000.

​
Step 3: Upload Your First Invoice

​
Using the Web Interface

1

Open the application

Navigate to http://localhost:3000 in your browser.
2

Choose your document

Drag and drop an invoice file, or click Browse Files to select from your computer. Supported formats:
  • Images: PNG, JPG, JPEG
  • Documents: PDF (single or multi-page)
  • Maximum size: 10MB
3

Select extraction mode

Choose how you want to process the invoice:
  • Structured JSON → India GST (v4): Best for Indian invoices, includes reconciliation
  • Structured JSON → Compact: MyBillBook schema format
  • Raw Text: Unstructured text extraction
4

Pick an AI model

Select from available OpenRouter models:
  • Gemini 2.5 Flash (Recommended) - Fast and accurate
  • GPT-4o Mini - OpenAI’s compact vision model
  • Gemini 2.5 Pro - Highest accuracy for complex invoices
5

Extract data

Click Extract Data and wait for processing (typically 3-8 seconds).
Pro tip: Use keyboard shortcuts for faster workflows:
  • ⌘K (Mac) or Ctrl+K (Windows/Linux) - Show keyboard shortcuts
  • ⌘Enter - Extract data
  • ⌘⇧C - Clear all

​
Using the API

Process invoices programmatically with direct API calls: 
curl -X POST http://localhost:3000/api/ocr-structured-v4 \
  -H "Content-Type: application/json" \
  -d '{
    "imageBase64": "data:image/png;base64,iVBORw0KG...",
    "mimeType": "image/png"
  }'

​
Step 4: Understand the Results

When processing completes, you’ll see three sections:

​
Document Preview

View the original uploaded document to verify correct file processing.

​
Structured Data

The right panel shows extracted invoice data with visual validation:
  • Green checkmark - Reconciliation passed (difference ≤ ₹0.05)
  • Red warning - Reconciliation failed (check reconciliation.error_absolute)
  • Line-by-line calculations showing quantity × rate, discounts, and taxes
  • Computed totals vs. printed totals comparison

​
Raw JSON (Toggle)

Click Show to view the complete API response:
Sample Response
{
  "doc_level": {
    "supplier_name": "ABC Corporation",
    "supplier_gstin": "27AAAAA1234A1Z5",
    "invoice_number": "INV-2024-001",
    "invoice_date": "2024-03-04",
    "place_of_supply_state_code": "27",
    "buyer_gstin": "27BBBBB5678B2Y4",
    "currency": "INR"
  },
  "items": [
    {
      "name": "Product A",
      "hsn": "8517",
      "qty": 10,
      "uom": "PCS",
      "rate_ex_tax": 100.00,
      "discount": {
        "d1_pct": 10.0,
        "d2_pct": null,
        "flat_per_unit": null,
        "effective_pct": 10.0,
        "amount": 100.00
      },
      "gst": {
        "rate": 18.0,
        "cgst": 81.00,
        "sgst": 81.00,
        "igst": 0.00,
        "amount": 162.00
      },
      "totals": {
        "line_ex_tax": 900.00,
        "line_inc_tax": 1062.00
      }
    }
  ],
  "totals": {
    "items_ex_tax": 900.00,
    "gst_total": 162.00,
    "grand_total": 1062.00
  },
  "reconciliation": {
    "error_absolute": 0.00,
    "alternates_considered": ["WITHOUT_TAX"],
    "warnings": []
  }
}

​
Step 5: Test the Review Tool

The Review Tool helps debug and verify OCR responses:
1

Navigate to the Review Tool

Click Review Tool in the top navigation, or go to http://localhost:3000/review.
2

Load sample data

Click Load sample to see a pre-filled example, or paste your own API response JSON.
3

Preview and analyze

Click Preview to see:
  • Auto-detected invoice schema (v4 or compact)
  • Line-by-line calculation breakdown
  • Reconciliation status with color-coded indicators
  • Detailed warnings and mismatches
The Review Tool automatically detects invoice objects in nested JSON structures, making it perfect for debugging LangFuse traces or API gateway logs.

​
Common Issues

​
Missing API Key Error

{
  "error": "Server missing OPENROUTER_API_KEY"
}
Solution: Ensure OPENROUTER_API_KEY is set in .env.local and restart the development server.

​
Parse Error

{
  "error": "Model did not return valid JSON (Unexpected token...)",
  "error_excerpt": "..."
}
Solution: Try a different model. Some models are better at strict JSON formatting:
  • Switch from GPT-4o Mini → Gemini 2.5 Flash
  • Use Gemini 2.5 Pro for complex multi-page invoices

​
High Reconciliation Error

If reconciliation.error_absolute > 0.05:
  1. Check if the invoice has unusual discount structures
  2. Verify GST rates are standard slabs (not custom rates)
  3. Review reconciliation.warnings for clues
  4. Use the Review Tool to inspect line-by-line calculations

​
Next Steps

Installation Guide

Complete setup instructions and environment configuration

API Reference

Detailed API documentation and schema references

Build docs developers (and LLMs) love

Get started for freeTalk to us