Die ITscope Connector REST API ermöglicht es Entwicklern, beliebige ERP-Systeme an den Connector anzubinden — nicht nur Odoo. Sämtliche Funktionen des Connectors (Produktsuche, KI-Anreicherung, Bestellabwicklung) sind über öffentlich dokumentierte REST-Endpunkte erreichbar.

Zielgruppe

Diese Referenz richtet sich an Entwickler und Integratoren, die eine eigene Anbindung an den ITscope Connector implementieren möchten. Für die fertige Odoo-Integration siehe Installation.

Base-URL

Alle API-Aufrufe erfolgen über die zentrale Base-URL:

https://api.connector.mateit.de/api/v1

Sämtliche in dieser Referenz dokumentierten Pfade sind relativ zu dieser Base-URL zu verstehen.

Authentifizierung

Jeder API-Request muss einen gültigen API-Key im HTTP-Header mitführen:

X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • API-Keys werden im Kundenportal erstellt und verwaltet — siehe API-Keys & Authentifizierung.
  • Format: sk_live_ gefolgt von 32 zufälligen Zeichen.
  • Ein Key wird nur einmalig beim Erstellen angezeigt; er muss sofort sicher gespeichert werden.
Sicherheit

API-Keys gewähren vollen Zugriff auf das jeweilige Konto. Sie dürfen niemals in Frontend-Code, Repositories oder Logs auftauchen. Kompromittierte Keys bitte umgehend im Portal widerrufen.

Request- und Response-Format

Eigenschaft Wert
Content-Type application/json
Encoding UTF-8
Datumsformat ISO 8601 (z. B. 2026-04-27T10:30:00Z)

Alle Request-Bodies und Response-Bodies werden als JSON übertragen. Datums- und Zeitangaben verwenden ausschließlich UTC mit Z-Suffix.

Fehler-Schema

Fehlerantworten folgen einem einheitlichen Schema:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Menschenlesbare Fehlerbeschreibung"
  }
}
  • code ist ein stabiler, maschinenlesbarer Bezeichner (z. B. INVALID_API_KEY, RATE_LIMIT_EXCEEDED).
  • message ist für Endnutzer geeignet und wird ggf. lokalisiert (siehe Sprach-Header).

HTTP-Statuscodes

Code Bedeutung
200 Erfolgreiche Anfrage
201 Ressource erstellt
204 Erfolgreich, keine Antwort
400 Ungültige Anfrage
401 Nicht authentifiziert (ungültiger API-Key)
403 Keine Berechtigung
404 Ressource nicht gefunden
429 Rate-Limit erreicht
500 Interner Serverfehler
503 ITscope-Dienst nicht erreichbar (Retry-After Header)

Rate-Limits

Zum Schutz der Plattformstabilität gelten folgende Standard-Limits pro Konto:

Limit-Typ Standard-Wert
API-Aufrufe 300 Requests pro Minute
KI-Aufrufe (LLM) 100 Anfragen pro Stunde
Parallele Verbindungen 5 gleichzeitige Requests

Individuelle Erhöhung

Benötigen Sie höhere Limits für Ihr Integrationsvolumen? Die Limits können individuell angepasst werden. Kontaktieren Sie uns unter support@mateit.de.

HTTP-Header

Bei Erreichen eines Limits erhalten Sie einen 429 Too Many Requests-Status mit folgenden Headern:

  • Retry-After — Sekunden bis zum nächsten erlaubten Request
  • X-RateLimit-Remaining — Verbleibende Requests im aktuellen Fenster
  • X-RateLimit-Reset — Unix-Timestamp des Fenster-Resets

Batch-Endpunkte

Die KI-Batch-Anreicherung hat ein eigenes internes Parallelitätslimit (8 gleichzeitige LLM-Aufrufe). Dadurch werden große Batch-Anfragen automatisch gedrosselt, ohne Ihr allgemeines API-Limit zu beeinflussen.

Implementieren Sie Exponential-Backoff in Ihrer Integration: Bei einem 429-Response warten Sie die im Retry-After-Header angegebene Zeit ab, bevor Sie den Request wiederholen.

Sprach-Header

Der Accept-Language-Header steuert die Sprache von Fehlermeldungen sowie KI-generierten Texten:

Accept-Language: de
  • Unterstützte Werte: de, en
  • Standard: en
  • Beeinflusst Fehlermeldungen sowie sprachabhängige Ausgaben der KI-Anreicherung.

Verfügbare Endpunkte

Die API ist in vier funktionale Bereiche gegliedert:

  • Produktsuche & Katalog — Suche, Filter und Detailabruf von ITscope-Produkten.
  • KI-Anreicherung — Automatische Generierung von Beschreibungen, Spezifikationen und Übersetzungen.
  • Bestellungen — Anlage, Übermittlung und Statusabfrage von Bestellungen.

Health-Check

Ein einfacher unauthentifizierter Health-Check zur Verfügbarkeitsprüfung:

curl -X GET "https://api.connector.mateit.de/api/v1/health"

Antwortet bei normalem Betrieb mit HTTP 200 und einem JSON-Body, der den Servicestatus beschreibt.