Invoice Scanner API

Welcome to the Invoice Scanner API documentation. Our API allows you to programmatically scan, extract, and manage invoice data from PDF and image files.

Authentication

The Invoice Scanner API uses API keys to authenticate requests. You can generate API keys from your dashboard.

curl https://invoicescan.eu/api/invoices \
  -H "X-API-Key: sk_your_api_key_here"

Rate Limits

API rate limits are based on your subscription plan:

Error Handling

The API uses conventional HTTP response codes to indicate success or failure:

Error Response Format

{
  "message": "Subscription limit exceeded",
  "errors": {
    "scans": ["You have used 10/10 scans this month"]
  }
}

Upload an invoice file (PDF, JPG, PNG, DOC, DOCX) for processing. The API will extract structured data from the invoice.

Endpoint

POST /api/invoices

Request Parameters

Example Request

curl -X POST https://invoicescan.eu/api/invoices \
  -H "X-API-Key: sk_your_api_key_here" \
  -F "file=@/path/to/invoice.pdf" \
  -F "company_vat_id=BG123456789" \
  -F "auto_create_company=true" \
  -F "webhook_url=https://your-app.com/webhook"

Response (202 Accepted)

{
  "message": "Invoice uploaded successfully",
  "job_id": "019a7307-ec8a-72c4-9b3c-1b2ce9196b10",
  "status": "pending"
}

Retrieve the processing status and extracted data for a specific invoice.

Endpoint

GET /api/invoices/{id}

Example Request

curl https://invoicescan.eu/api/invoices/019a7307-ec8a-72c4-9b3c-1b2ce9196b10 \
  -H "X-API-Key: sk_your_api_key_here"

Response (200 OK)

{
  "job_id": "019a7307-ec8a-72c4-9b3c-1b2ce9196b10",
  "status": "completed",
  "result": {
    "invoice_number": "082000530981",
    "invoice_date": "15/10/2025",
    "vendor_name": "Hetzner Online GmbH",
    "vendor_address": "Industriestr. 25, 91710 Gunzenhausen, Germany",
    "customer_name": "MICROWEBER FINANCE EOOD",
    "customer_address": "Mr. Peter Ivanov, Bratq Chakrin 10, 1000 Sofia, Bulgaria",
    "line_items": [
      {
        "description": "AX41-NVMe Dedicated Server",
        "quantity": 288,
        "unit_price": "€0.0571",
        "total": "€16.4448"
      }
    ],
    "subtotal": "€310.42",
    "tax": "€0.00",
    "grand_total": "€310.42"
  },
  "error": null,
  "created_at": "2025-11-11T13:08:10Z",
  "updated_at": "2025-11-11T13:09:45Z"
}

Retrieve a paginated list of all your invoices with optional filtering.

Endpoint

GET /api/invoices

Query Parameters

Example Request

curl "https://invoicescan.eu/api/invoices?page=1&status=completed&company_vat_id=BG123456789" \
  -H "X-API-Key: sk_your_api_key_here"

Response (200 OK)

{
  "data": [
    {
      "job_id": "019a7307-ec8a-72c4-9b3c-1b2ce9196b10",
      "status": "completed",
      "session_id": null,
      "created_at": "2025-11-11T13:08:10Z",
      "updated_at": "2025-11-11T13:09:45Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 1
  }
}

Delete a specific invoice by its job ID.

Endpoint

DELETE /api/invoices/{id}

Example Request

curl -X DELETE https://invoicescan.eu/api/invoices/019a7307-ec8a-72c4-9b3c-1b2ce9196b10 \
  -H "X-API-Key: sk_your_api_key_here"

Response (200 OK)

{
  "message": "Invoice deleted successfully"
}

Upload and process an invoice synchronously. This endpoint waits for processing to complete and returns the extracted data immediately. Maximum wait time is configurable.

Endpoint

POST /api/invoices

Example Request

curl -X POST https://invoicescan.eu/api/invoices \
  -H "X-API-Key: sk_your_api_key_here" \
  -F "file=@/path/to/invoice.pdf"

# Then poll for results
curl https://invoicescan.eu/api/invoices/{job_id} \
  -H "X-API-Key: sk_your_api_key_here"

Generate a QR code that redirects to the invoice scanner. Optionally link to a specific company.

Endpoint

POST /api/invoices/qr

Request Body

Example Request

curl -X POST https://invoicescan.eu/api/invoices/qr \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"company_id": 1}'

Returns an SVG QR code image that can be displayed or saved.

Response

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="200" height="200">
  <!-- QR Code SVG content -->
</svg>

Retrieve a paginated list of all companies associated with your account.

Endpoint

GET /api/companies

Example Request

curl https://invoicescan.eu/api/companies \
  -H "X-API-Key: sk_your_api_key_here"

Response (200 OK)

{
  "data": [
    {
      "id": 1,
      "name": "ACME Corporation",
      "vat_number": "BG123456789",
      "address": "123 Business St",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 1
  }
}

Create a new company in your account.

Endpoint

POST /api/companies

Request Body

Example Request

curl -X POST https://invoicescan.eu/api/companies \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Corporation",
    "vat_number": "BG123456789",
    "address": "123 Business St, Sofia, Bulgaria"
  }'

Response (201 Created)

{
  "id": 1,
  "name": "ACME Corporation",
  "vat_number": "BG123456789",
  "address": "123 Business St, Sofia, Bulgaria",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Update an existing company's information.

Endpoint

PUT /api/companies/{id}

Example Request

curl -X PUT https://invoicescan.eu/api/companies/1 \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Corp Updated"
  }'

Retrieve details of a specific company by ID.

Endpoint

GET /api/companies/{id}

Example Request

curl https://invoicescan.eu/api/companies/1 \
  -H "X-API-Key: sk_your_api_key_here"

Response (200 OK)

{
  "id": 1,
  "name": "ACME Corporation",
  "vat_number": "BG123456789",
  "tax_id": "123456789",
  "address": "123 Business St, Sofia, Bulgaria",
  "email": null,
  "phone": null,
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Update an existing company's information.

Endpoint

PUT /api/companies/{id}

Example Request

curl -X PUT https://invoicescan.eu/api/companies/1 \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Corp Updated",
    "email": "contact@acmecorp.com"
  }'

Delete a company from your account.

Endpoint

DELETE /api/companies/{id}

Example Request

curl -X DELETE https://invoicescan.eu/api/companies/1 \
  -H "X-API-Key: sk_your_api_key_here"

Get all invoices associated with a specific company.

Endpoint

GET /api/companies/{company_id}/invoices

Query Parameters

Example Request

curl "https://invoicescan.eu/api/companies/1/invoices?status=completed&page=1" \
  -H "X-API-Key: sk_your_api_key_here"

Response (200 OK)

{
  "data": [
    {
      "job_id": "019a7307-ec8a-72c4-9b3c-1b2ce9196b10",
      "status": "completed",
      "company_id": 1,
      "created_at": "2025-11-11T13:08:10Z",
      "updated_at": "2025-11-11T13:09:45Z",
      "result": {
        "invoice_number": "INV-2025-001",
        "grand_total": "€1,200.00",
        "..."
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 20,
    "total": 57
  }
}

Extract company information from a document using AI (e.g., business card, letterhead).

Endpoint

POST /api/companies/extract

Request Parameters

Example Request

curl -X POST https://invoicescan.eu/api/companies/extract \
  -H "X-API-Key: sk_your_api_key_here" \
  -F "file=@business_card.jpg"

Response (200 OK)

{
  "name": "Extracted Company Ltd",
  "vat_number": "BG123456789",
  "address": "123 Business Street, Sofia",
  "email": "contact@extracted.com",
  "phone": "+359 2 123 4567",
  "website": "https://extracted.com"
}

Get all vendors for a specific company.

Endpoint

GET /api/companies/{company_id}/vendors

Example Request

curl https://invoicescan.eu/api/companies/1/vendors \
  -H "X-API-Key: sk_your_api_key_here"

Add a new vendor to a company.

Endpoint

POST /api/companies/{company_id}/vendors

Request Body

Example Request

curl -X POST https://invoicescan.eu/api/companies/1/vendors \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_name": "Office Supplies Inc",
    "vendor_vat": "VAT123456"
  }'

📊 Account Codes & Document Classification

{
  "job_id": "019c763c-3196-706f-83eb-ca2f585f62f9",
  "status": "completed",
  "result": {
    // AI-Extracted Classification (Bulgarian Standards)
    "document_code": "601",
    "document_code_description": "Разходи за материали",
    "document_code_group": "60 - Operating Expenses",
    "document_code_confidence": 0.95,
    "document_code_reasoning": "Line items contain materials...",
    
    // Bulgarian VAT Classification
    "document_type_code": "01",
    "document_type_description": "Фактура",
    
    // Invoice Details
    "invoice_number": "INV-2025-001",
    "invoice_date": "2025-01-15",
    "vendor_name": "Supplier Ltd",
    "grand_total": "€1,200.00",
    
    // Line Items (may include your account codes if mapped)
    "line_items": [
      {
        "description": "Office Materials",
        "quantity": 10,
        "unit_price": "€100.00",
        "total": "€1,000.00",
        "account_code": "60101"  // Your custom code (if mapped)
      }
    ]
  }
}

Get all account codes for a specific company.

Endpoint

GET /api/companies/{company_id}/account-codes

Example Request

curl https://invoicescan.eu/api/companies/1/account-codes \
  -H "X-API-Key: sk_your_api_key_here"

Add a new account code to a company.

Endpoint

POST /api/companies/{company_id}/account-codes

Request Body

Example Request

curl -X POST https://invoicescan.eu/api/companies/1/account-codes \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "account_code": "6000",
    "account_name": "Office Supplies",
    "account_type": "expense"
  }'

Import multiple account codes at once from tab-separated text.

Endpoint

POST /api/companies/{company_id}/account-codes/bulk-import

Request Body

Example Request

curl -X POST https://invoicescan.eu/api/companies/1/account-codes/bulk-import \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "pasted_text": "100\tCash\n200\tBank\n300\tAccounts Receivable"
  }'

Delete multiple account codes at once.

Endpoint

POST /api/companies/{company_id}/account-codes/bulk-delete

Request Body

Example Request

curl -X POST https://invoicescan.eu/api/companies/1/account-codes/bulk-delete \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [1, 2, 3, 4, 5]
  }'

PHP SDK Example

Example using PHP to upload and process an invoice:

<?php

$apiKey = 'sk_your_api_key_here';
$apiUrl = 'https://invoicescan.eu/api/invoices';

// Upload invoice
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $apiUrl,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
    ],
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('/path/to/invoice.pdf'),
        'webhook_url' => 'https://your-app.com/webhook',
    ],
]);

$response = curl_exec($curl);
$result = json_decode($response, true);
curl_close($curl);

// Get job_id
$jobId = $result['job_id'];

// Poll for result
$maxAttempts = 30;
for ($i = 0; $i < $maxAttempts; $i++) {
    sleep(2);
    
    $curl = curl_init();
    curl_setopt_array($curl, [
        CURLOPT_URL => $apiUrl . '/' . $jobId,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $apiKey,
        ],
    ]);
    
    $response = curl_exec($curl);
    $result = json_decode($response, true);
    curl_close($curl);
    
    if ($result['status'] === 'completed') {
        print_r($result['result']);
        break;
    }
}

Analyze a PDF file and extract each page as a base64 encoded image. This endpoint processes PDF files page-by-page and returns high-quality image representations of each page.

Endpoint

POST /api/invoices-file-analyze

Authentication

This endpoint requires authentication via Sanctum (session-based auth).

Request Parameters

Example Request (cURL)

curl -X POST https://invoicescan.eu/api/invoices-file-analyze \
  -H "Accept: application/json" \
  -H "Cookie: your-session-cookie" \
  -F "file=@/path/to/document.pdf" \
  -F "scale=2.0" \
  -F "format=jpeg" \
  -F "quality=0.85"

Example Request (JavaScript)

const formData = new FormData();
formData.append('file', pdfFile);
formData.append('scale', 2.0);
formData.append('format', 'jpeg');
formData.append('quality', 0.85);

const response = await fetch('/api/invoices-file-analyze', {
  method: 'POST',
  headers: {
    'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content
  },
  credentials: 'include',
  body: formData
});

const result = await response.json();
console.log(result);

Success Response (200 OK)

{
  "success": true,
  "numPages": 3,
  "pages": [
    {
      "pageNumber": 1,
      "width": 1654,
      "height": 2339,
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    {
      "pageNumber": 2,
      "width": 1654,
      "height": 2339,
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    {
      "pageNumber": 3,
      "width": 1654,
      "height": 2339,
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
    }
  ]
}

Error Response (500 Internal Server Error)

{
  "success": false,
  "error": "Failed to analyze PDF",
  "details": "Error message details..."
}