API Documentation

External REST API for integrating AV Timber OCR data into other systems.

Authentication

All requests require an API key passed via the X-API-Key header.

Set the key in .env.local:

EXTERNAL_API_KEY=your_secret_key

Endpoints

GET

/api/external/documents

Returns a list of all processed documents with summary information.

Example request

curl -H "X-API-Key: your_secret_key" \ http://localhost:3000/api/external/documents

Response

[
  {
    "id": "4025751c-54d1-4040-b118-77bfb3ce3aa6",
    "status": "completed",
    "documentNumber": "2026-173",
    "documentDate": "2026-03-12",
    "supplierName": "Holz Schnell GmbH",
    "totalVolumeM3": 43.484,
    "createdAt": "2026-06-09T06:14:53.996Z"
  }
]

GET

/api/external/documents/{id}

Returns the full structured OCR data for a single document.

Example request

curl -H "X-API-Key: your_secret_key" \ http://localhost:3000/api/external/documents/4025751c-54d1-4040-b118-77bfb3ce3aa6

Response

{
  "document": {
    "documentType": "Lieferschein",
    "documentNumber": "2026-173",
    "documentDate": "2026-03-12",
    "deliveryDate": "2026-03-12",
    "reference": "RSN6962",
    "customerNumber": "24866",
    "pageNumber": 1,
    "processedAt": "2026-06-09T06:14:57.278Z"
  },
  "supplier": {
    "name": "Holz Schnell GmbH",
    "vatId": "ATU 57638989",
    "address": {
      "street": "Wagrainer Str. 4",
      "postalCode": "A-5542",
      "city": "Flachau",
      "country": "Austria"
    }
  },
  "customer": {
    "name": "AV-Timber GmbH",
    "address": {
      "street": "Stiegengasse 5",
      "postalCode": "1060",
      "city": "WIEN"
    }
  },
  "positions": [
    {
      "positionId": 1,
      "productDescription": "Prism. Ware f, Fi/Ta, 0/III",
      "thicknessMm": 35,
      "widthMm": 172,
      "lengthM": 3,
      "pieces": 168,
      "volumeM3": 3.034
    }
  ],
  "totals": {
    "totalVolumeM3": 43.484,
    "totalPieces": 1848
  },
  "deliveryTerms": "CPT frei Ankunft"
}

Error Codes

Status	Response	Cause
401	{ "error": "Unauthorized" }	Missing or invalid X-API-Key
404	{ "error": "Document not found" }	Document ID does not exist
400	{ "error": "Document is ..." }	Document not yet processed or missing ID

Schema Reference

Field	Type	Description
document.documentType	string	Always "Lieferschein"
document.documentNumber	string	Delivery note number
document.documentDate	string	ISO 8601 date (YYYY-MM-DD)
document.deliveryDate	string	ISO 8601 date (YYYY-MM-DD)
document.reference	string	Reference code (e.g. RSN number)
document.customerNumber	string	Customer number
supplier.name	string	Supplier company name
supplier.vatId	string	VAT identification number
supplier.address	object	street, postalCode, city, country
positions[].positionId	integer	Line position number
positions[].productDescription	string	Timber product description
positions[].thicknessMm	number	Thickness in millimeters
positions[].widthMm	number	Width in millimeters
positions[].lengthM	number	Length in meters
positions[].pieces	number	Piece count
positions[].volumeM3	number	Volume in cubic meters
totals.totalVolumeM3	number	Total volume
totals.totalPieces	number	Total piece count
totals.totalPackages	number	Total package count (if available)
deliveryTerms	string	Incoterms or delivery conditions

All fields are optional — only fields detected by OCR are returned.

Integration Example

Fetch all documents, then request details for each one:

API_KEY="your_secret_key" BASE="http://localhost:3000" # List all documents curl -H "X-API-Key: $API_KEY" "$BASE/api/external/documents" | jq . # Get details for a specific document curl -H "X-API-Key: $API_KEY" \ "$BASE/api/external/documents/4025751c-54d1-4040-b118-77bfb3ce3aa6" | jq .