API Documentation

Authentication

The API requires CSRF token validation for POST requests. Include the token in the x-csrf-token header.

curl -H "x-csrf-token: YOUR_CSRF_TOKEN" https://api.example.com/api/process-invoice

Endpoints

POST /api/process-invoice

Upload and process an invoice document

curl -X POST -F "file=@invoice.pdf" \
  -H "x-csrf-token: TOKEN" \
  https://api.example.com/api/process-invoice

Response:

{
  "invoice_number": "INV-001",
  "invoice_date": "2024-03-01",
  "sender_name": "ACME Corp",
  "recipient_name": "Widget Inc",
  "total": "$1,000.00",
  "saved_to_database": true,
  "invoice_id": 42
}

GET /api/invoices

Retrieve list of saved invoices

curl https://api.example.com/api/invoices?skip=0&limit=50

GET /api/invoices/:id

Get detailed information about a specific invoice

curl https://api.example.com/api/invoices/42

GET /api/health

Check API server and database health status

curl https://api.example.com/api/health

Error Codes

Code	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Invalid request parameters
403	Forbidden	CSRF validation failed
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
422	Unprocessable Entity	OCR processing failed
500	Server Error	Internal server error

Rate Limiting

API endpoints are rate-limited to 10 requests per 60 seconds per client IP.

If you exceed the limit, the API will return a 429 response with the following header:

Retry-After: 30

Supported File Formats

• ✓ PDF (.pdf)
• ✓ PNG (.png)
• ✓ JPEG (.jpg, .jpeg)
• ✓ TIFF (.tiff)
• ✓ Bitmap (.bmp)

Max file size: 50MB

Example: Python Client

import requests

url = 'https://api.example.com/api/process-invoice'
csrf_token = 'YOUR_CSRF_TOKEN'

with open('invoice.pdf', 'rb') as f:
    files = {'file': f}
    data = {'turnstile_token': 'test_token'}
    headers = {'x-csrf-token': csrf_token}
    
    response = requests.post(url, files=files, data=data, headers=headers)
    result = response.json()
    
    print(f"Invoice: {result['invoice_number']}")
    print(f"Total: {result['total']}")
    print(f"Saved: {result['saved_to_database']}")