API-Dokumentation

API-Schlüssel erstellen

1. 1. Melde dich in deinem Rechnio-Dashboard an.
2. 2. Navigiere zu Einstellungen → API-Keys.
3. 3. Klicke auf „Neuen API-Key generieren".
4. 4. Kopiere den angezeigten Schlüssel — er wird nur einmal angezeigt.

Schlüsselformat

Alle API-Schlüssel beginnen mit dem Präfix rechnio_live_ gefolgt von 48 zufälligen hexadezimalen Zeichen. Schlüssel werden nur als SHA-256-Hash in der Datenbank gespeichert.

GET /api/v1/customers

Gibt eine paginierte Liste aller Kunden zurück.

Query-Parameter

curl -X GET "https://rechnio.at/api/v1/customers?limit=10&search=Muster" \
  -H "Authorization: Bearer rechnio_live_xxx"

{
  "total": 42,
  "limit": 10,
  "offset": 0,
  "items": [
    {
      "id": "clx...",
      "customerNumber": "K-00001",
      "company": "Musterfirma GmbH",
      "firstName": null,
      "lastName": null,
      "email": "office@musterfirma.at",
      "phone": "+43 512 123456",
      "addressLine1": "Musterstraße 1",
      "city": "Innsbruck",
      "postalCode": "6020",
      "country": "AT",
      "vatId": "ATU12345678",
      "notes": null,
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

POST /api/v1/customers

Legt einen neuen Kunden an. Entweder company oder firstName/lastName ist erforderlich.

Request Body

curl -X POST "https://rechnio.at/api/v1/customers" \
  -H "Authorization: Bearer rechnio_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "Neue Firma GmbH",
    "email": "office@neuefirma.at",
    "country": "AT",
    "vatId": "ATU87654321"
  }'

Antwort: 201 Created — das angelegte Kundenobjekt. Löst Webhook-Event customer.created aus.

GET /api/v1/invoices

Gibt eine paginierte Liste aller Rechnungen zurück, sortiert nach Rechnungsdatum (neueste zuerst).

Query-Parameter

curl "https://rechnio.at/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer rechnio_live_xxx"

{
  "total": 138,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "id": "clx...",
      "invoiceNumber": "R-2025-0042",
      "status": "paid",
      "invoiceDate": "2025-03-01T00:00:00.000Z",
      "dueDate": "2025-03-15T00:00:00.000Z",
      "subtotal": 1000,
      "vatRate": 20,
      "vatAmount": 200,
      "total": 1200,
      "currency": "EUR",
      "customer": {
        "id": "clx...",
        "company": "Musterfirma GmbH",
        "email": "office@musterfirma.at"
      },
      "items": [
        {
          "position": 1,
          "description": "Webentwicklung",
          "quantity": 10,
          "unit": "Std.",
          "unitPrice": 100,
          "totalPrice": 1000
        }
      ]
    }
  ]
}

POST /api/v1/invoices

Erstellt eine neue Rechnung im Status draft. Die Rechnungsnummer wird automatisch aus der angegebenen Serie generiert.

Request Body

items – Felder pro Position

curl -X POST "https://rechnio.at/api/v1/invoices" \
  -H "Authorization: Bearer rechnio_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "seriesId": "clx...",
    "customerId": "clx...",
    "invoiceDate": "2025-06-01",
    "vatRate": 20,
    "items": [
      {
        "description": "Webentwicklung Juni 2025",
        "quantity": 20,
        "unit": "Std.",
        "unitPrice": 95
      }
    ],
    "notes": "Zahlbar innerhalb 14 Tagen."
  }'

Antwort: 201 Created — das erstellte Rechnungsobjekt inkl. generierter Rechnungsnummer. Löst Webhook-Event invoice.created aus.

GET /api/v1/transactions

Gibt Banktransaktionen zurück, optional gefiltert nach Datumsbereich, Kategorie oder Konto.

Query-Parameter

curl "https://rechnio.at/api/v1/transactions?from=2025-01-01&to=2025-03-31" \
  -H "Authorization: Bearer rechnio_live_xxx"

{
  "total": 95,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "id": "clx...",
      "amount": "1200.00",
      "description": "Zahlung Musterfirma GmbH",
      "category": "Einnahmen",
      "accountId": "clx...",
      "bookingDate": "2025-03-05T00:00:00.000Z",
      "valueDate": "2025-03-05T00:00:00.000Z",
      "account": {
        "id": "clx...",
        "name": "Geschäftskonto"
      }
    }
  ]
}

GET /api/v1/receipts

Gibt hochgeladene Belege zurück, die per KI (OCR) verarbeitet wurden.

Query-Parameter

curl "https://rechnio.at/api/v1/receipts?status=unassigned" \
  -H "Authorization: Bearer rechnio_live_xxx"

{
  "total": 12,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "id": "clx...",
      "originalName": "rechnung-amazon.pdf",
      "fileSize": 48392,
      "mimeType": "application/pdf",
      "fileUrl": "/uploads/receipts/xxx.pdf",
      "ocrDate": "2025-02-14T00:00:00.000Z",
      "ocrAmount": "29.90",
      "ocrCurrency": "EUR",
      "ocrCounterparty": "Amazon EU S.à r.l.",
      "ocrDescription": "AWS Services Februar 2025",
      "ocrDocumentType": "Rechnung",
      "transactionId": null,
      "createdAt": "2025-02-15T09:12:43.000Z"
    }
  ]
}

Webhook einrichten

1. 1. Gehe zu Einstellungen → Webhooks im Dashboard.
2. 2. Trage deine Empfänger-URL ein (muss HTTPS sein).
3. 3. Wähle die Ereignisse, die du empfangen möchtest.
4. 4. Kopiere das generierte Webhook-Secret für die Signaturprüfung.

Verfügbare Ereignisse

Signaturprüfung (HMAC-SHA256)

Rechnio signiert jeden Webhook-Request mit dem Webhook-Secret. Überprüfe die Signatur, um sicherzustellen, dass der Request von Rechnio stammt.

Header

X-Rechnio-Signature: sha256=<hmac-sha256-hex>

Verifikation (Node.js)

import crypto from 'crypto'

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

// In deinem Webhook-Handler:
const rawBody = await req.text()
const sig = req.headers.get('x-rechnio-signature') ?? ''
if (!verifyWebhook(rawBody, sig, process.env.WEBHOOK_SECRET!)) {
  return new Response('Unauthorized', { status: 401 })
}

Payload-Format

{
  "event": "invoice.created",
  "tenantId": "clx...",
  "data": {
    "id": "clx...",
    "invoiceNumber": "R-2025-0043",
    "status": "draft",
    ...
  }
}

JavaScript / TypeScript (fetch)

const API_KEY = process.env.RECHNIO_API_KEY // rechnio_live_xxx
const BASE_URL = 'https://rechnio.at/api/v1'

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
}

// Kunden abrufen
const res = await fetch(`${BASE_URL}/customers?limit=50`, { headers })
const { items, total } = await res.json()
console.log(`${total} Kunden gefunden`)

// Neuen Kunden anlegen
const newCustomer = await fetch(`${BASE_URL}/customers`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    company: 'Neue GmbH',
    email: 'info@neue-gmbh.at',
    country: 'AT',
  }),
}).then(r => r.json())

// Bezahlte Rechnungen der letzten 30 Tage
const since = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0]
const invoices = await fetch(
  `${BASE_URL}/invoices?status=paid&limit=100`,
  { headers }
).then(r => r.json())

Python (requests)

import requests, os

API_KEY = os.environ['RECHNIO_API_KEY']
BASE_URL = 'https://rechnio.at/api/v1'
headers = {'Authorization': f'Bearer {API_KEY}'}

# Kunden abrufen
r = requests.get(f'{BASE_URL}/customers', headers=headers, params={'limit': 50})
data = r.json()
print(f"{data['total']} Kunden")

# Neuen Kunden anlegen
r = requests.post(f'{BASE_URL}/customers', headers=headers, json={
    'company': 'Neue GmbH',
    'email': 'info@neue-gmbh.at',
    'country': 'AT',
})
print(r.json()['customerNumber'])  # z.B. K-00015

cURL

# Kundenliste abrufen
curl "https://rechnio.at/api/v1/customers?limit=10" \
  -H "Authorization: Bearer rechnio_live_xxx"

# Neuen Kunden anlegen
curl -X POST "https://rechnio.at/api/v1/customers" \
  -H "Authorization: Bearer rechnio_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"company":"Test GmbH","email":"test@example.at","country":"AT"}'

# Rechnungen nach Status filtern
curl "https://rechnio.at/api/v1/invoices?status=paid&limit=5" \
  -H "Authorization: Bearer rechnio_live_xxx"

# Transaktionen nach Datumsbereich
curl "https://rechnio.at/api/v1/transactions?from=2025-01-01&to=2025-12-31" \
  -H "Authorization: Bearer rechnio_live_xxx"