Leitfaden zur API-Integration

Erstellen Sie leistungsfähige Integrationen mit der REST-API von Operate. Dieser Leitfaden behandelt die Authentifizierung, das Absetzen von Anfragen und bewährte Vorgehensweisen.

Authentifizierung

Operate unterstützt zwei Authentifizierungsverfahren:

API-Schlüssel (empfohlen für Integrationen)

Erzeugen Sie API-Schlüssel im Entwicklerportal für die Authentifizierung zwischen Diensten.

// Mit Bearer-Token
fetch('https://operate.guru/api/v1/invoices', {
  headers: {
    'Authorization': 'Bearer op_live_your_api_key',
    'Content-Type': 'application/json'
  }
});

// Oder mit dem Header X-API-Key
fetch('https://operate.guru/api/v1/invoices', {
  headers: {
    'X-API-Key': 'op_live_your_api_key',
    'Content-Type': 'application/json'
  }
});

Arten von API-Schlüsseln

• Live-Schlüssel (op_live_...): für den Produktivbetrieb
• Test-Schlüssel (op_test_...): für Entwicklung und Tests

Berechtigungen der Schlüssel

• READ_ONLY: darf Daten nur lesen
• READ_WRITE: darf Daten lesen und schreiben
• ADMIN: voller Zugriff einschließlich Einstellungen

Anfragen absetzen

Basis-URL

https://operate.guru/api/v1

Häufig genutzte Endpunkte

Seitenweise Abfrage

Endpunkte, die Listen liefern, unterstützen eine seitenweise Abfrage:

// Seite 2 mit 50 Einträgen pro Seite abrufen
GET /api/v1/invoices?page=2&limit=50

Filtern

Filtern Sie die Ergebnisse über Query-Parameter:

// Bezahlte Rechnungen aus Jänner 2024 abrufen
GET /api/v1/invoices?status=PAID&from=2024-01-01&to=2024-01-31

Fehlerbehandlung

Die API liefert die üblichen HTTP-Statuscodes:

Aufbau der Fehlerantwort

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be positive"
    }
  ]
}

Ratenlimits

Die Antworten enthalten Header zum Ratenlimit:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

Idempotenz

So vermeiden Sie doppelte Datensätze, wenn Sie fehlgeschlagene Anfragen wiederholen:

Idempotenzschlüssel

Setzen Sie bei POST- und PUT-Anfragen den Header Idempotency-Key:

fetch('https://operate.guru/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer op_live_your_api_key',
    'Idempotency-Key': 'unique_key_12345',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ /* Rechnungsdaten */ })
});

So funktioniert es

1. Erste Anfrage: Die Rechnung wird angelegt, der Schlüssel 24 Stunden lang gespeichert
2. Wiederholte Anfrage (gleicher Schlüssel innerhalb von 24 Stunden): liefert dieselbe Rechnung zurück (es entsteht keine Dublette)
3. Nach 24 Stunden: Der Schlüssel verfällt, eine neue Rechnung würde angelegt

Schlüssel erzeugen

Verwenden Sie UUID v4 oder Ähnliches:

// Node.js
const { v4: uuidv4 } = require('uuid');
const key = uuidv4();

// Python
import uuid
key = str(uuid.uuid4())

Seitenweise Abfrage & Sortierung

Parameter für die seitenweise Abfrage

Beispiel

// Zweite Seite mit 50 Einträgen abrufen
GET /api/v1/invoices?page=2&limit=50

Aufbau der Antwort

{
  "data": [ /* Rechnungsobjekte */ ],
  "meta": {
    "page": 2,
    "limit": 50,
    "total": 247,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPreviousPage": true
  },
  "links": {
    "first": "/api/v1/invoices?page=1&limit=50",
    "previous": "/api/v1/invoices?page=1&limit=50",
    "next": "/api/v1/invoices?page=3&limit=50",
    "last": "/api/v1/invoices?page=5&limit=50"
  }
}

Sortierung

Verwenden Sie sortBy und sortOrder:

// Nach Datum sortieren, neueste zuerst
GET /api/v1/invoices?sortBy=createdAt&sortOrder=desc

// Nach Betrag sortieren, niedrigster zuerst
GET /api/v1/expenses?sortBy=amount&sortOrder=asc

Erweiterte Filter

Filtern nach Zeitraum

// Rechnungen, die im Jänner 2024 angelegt wurden
GET /api/v1/invoices?from=2024-01-01&to=2024-01-31

// Ausgaben der letzten 30 Tage
GET /api/v1/expenses?from=2024-01-01

Filtern nach Status

// Nur bezahlte Rechnungen
GET /api/v1/invoices?status=PAID

// Mehrere Status
GET /api/v1/invoices?status=PAID,PARTIALLY_PAID

Suche nach Feld

// Rechnung anhand der Nummer finden
GET /api/v1/invoices?number=INV-2024-001

// Kundin bzw. Kunden anhand des Namens finden
GET /api/v1/clients?name=Acme Corp

Filter kombinieren

// Bezahlte Rechnungen aus Jänner mit Beträgen über 1.000 €
GET /api/v1/invoices?status=PAID&from=2024-01-01&to=2024-01-31&minAmount=1000

Versionierung

Aktuelle Version

API-Version: v1

Basis-URL: https://operate.guru/api/v1

Version in der URL

Die API-Version steht im URL-Pfad (nicht im Header):

https://operate.guru/api/v1/invoices  ✅ Richtig
https://operate.guru/api/invoices     ❌ Version fehlt

Künftige Versionen

Wenn v2 erscheint:

• v1 bleibt mindestens 12 Monate verfügbar
• Hinweise zur Abkündigung werden 6 Monate vor dem Support-Ende versendet
• Ein Migrationsleitfaden wird bereitgestellt

Bewährte Vorgehensweisen

1. API-Schlüssel sicher verwahren – Schlüssel nie in Client-Code oder Git-Repositories preisgeben
2. Ratenlimits berücksichtigen – exponentielles Backoff mit Jitter umsetzen
3. Webhooks nutzen – für Aktualisierungen in Echtzeit statt Polling
4. Antworten prüfen – Statuscodes auswerten und Fehler sauber behandeln
5. Idempotenzschlüssel setzen – bei POST- und PUT-Anfragen, um Dubletten zu vermeiden
6. Wo möglich zwischenspeichern – weniger kritische Daten cachen und so Aufrufe sparen
7. Große Abfragen aufteilen – nicht alle Datensätze auf einmal abrufen
8. Zeitlimits setzen – hängende Anfragen vermeiden (30 s empfohlen)
9. API-Fehler protokollieren – Fehlerprotokolle für die Fehlersuche aufbewahren
10. In der Sandbox testen – Test-Schlüssel vor dem Produktivbetrieb verwenden

Codebeispiele

Node.js

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://operate.guru/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.OPERATE_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Rechnung anlegen
const invoice = await api.post('/invoices', {
  customerName: 'Acme Corp',
  items: [
    { description: 'Consulting', quantity: 10, unitPrice: 150 }
  ],
  currency: 'EUR',
  vatRate: 20
});

Python

import requests

headers = {
    'Authorization': f'Bearer {os.environ["OPERATE_API_KEY"]}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://operate.guru/api/v1/invoices',
    headers=headers
)
invoices = response.json()

OpenAPI-Spezifikation

Die vollständige OpenAPI-Spezifikation finden Sie hier:

• JSON: https://operate.guru/api/openapi.json
• Interaktive Dokumentation: https://operate.guru/api-docs/reference

Nächste Schritte

• Webhooks einrichten für Ereignisse in Echtzeit
• API-Referenz erkunden für alle Endpunkte
• Erste Integration erstellen