API — Einstieg & Übersicht

Mit der configento.app API verwaltest du deine Konfiguratoren programmatisch — Komponenten, Gruppen, Merkmale, Werte, Regeln und Preislisten lesen, anlegen und ändern und Änderungen veröffentlichen. Ideal, wenn du Daten aus einem PIM- oder ERP-System überträgst.

Authentifizierung

Jede Anfrage braucht einen API-Schlüssel im Authorization-Header:

Authorization: Bearer DEIN_API_SCHLUESSEL
Accept: application/json
Content-Type: application/json

API-Schlüssel erstellst du im V3-Backend unter Einstellungen → API: Namen eingeben, Berechtigung wählen, optional ein Ablaufdatum setzen, Erstellen klicken. Der Schlüssel wird nur einmal angezeigt — kopiere ihn sofort und bewahre ihn sicher auf.

Wichtig:

• Ein Schlüssel gehört zu dem Dienst (Service Order), der beim Erstellen ausgewählt war, und arbeitet nur mit dessen Komponenten.
• Du kannst beliebig viele Schlüssel anlegen — am besten einen pro Integration, damit du einzelne gezielt widerrufen kannst.
• Optional bekommt ein Schlüssel ein Ablaufdatum: Er funktioniert bis zum Ende dieses Tages und wird danach mit 401 abgelehnt. Das Datum kannst du jederzeit verschieben oder entfernen — auch ein bereits abgelaufener Schlüssel wird so wieder gültig. Ohne Datum läuft ein Schlüssel nie ab.
• Schlüssel verwaltest du ausschließlich im Backend. Über die API selbst lassen sich keine Schlüssel anlegen, ändern oder löschen.

Berechtigungen

Veröffentlichen und KI lassen sich nur zusammen mit Lesen & Schreiben vergeben und sind beim Erstellen standardmäßig aus. So kann zum Beispiel ein PIM Preise und Werte im Entwurf pflegen, während ein Mensch prüft und veröffentlicht. Die Berechtigungen eines Schlüssels kannst du jederzeit in der Liste ändern — sie gelten ab der nächsten Anfrage.

Für keinen Schlüssel verfügbar, unabhängig von der Berechtigung: Schlüssel verwalten, KI-Tokens kaufen, Integrations-Zugangsdaten (Shop-Plugins, HTML5-Snippet) lesen oder erneuern. Das bleibt dem Backend vorbehalten — ein abhandengekommener Schlüssel kann sich so weder einen Ersatz ausstellen noch Kosten verursachen.

Basis-URL

https://admin.configento.app/api/v1

Datenmodell

Komponente
├── Gruppen
│   └── Merkmale
│       └── Werte
└── Regeln

Komponenten mit positiver ID sind veröffentlicht, Komponenten mit negativer ID sind noch unveröffentlichte Entwürfe. Alle Änderungen über die API landen zunächst im Entwurf — erst Veröffentlichen bringt sie in den Shop.

Die wichtigsten Endpunkte

Komponenten

GET    /components                          # Alle Komponenten auflisten
GET    /components/{id}                     # Komponente mit Gruppen, Merkmalen, Werten und Regeln
POST   /components                          # Neue leere Komponente anlegen
PUT    /components/{id}                     # Einstellungen der Komponente ändern
DELETE /components/{id}                     # Komponente löschen (auch live!)  — Veröffentlichen
POST   /components/{id}/duplicate           # Komponente kopieren

Gruppen und Merkmale

POST   /components/{id}/groups                              # Gruppe anlegen
PUT    /components/{id}/groups/{gid}                        # Gruppe ändern
DELETE /components/{id}/groups/{gid}                        # Gruppe löschen
POST   /components/{id}/groups/{gid}/characteristics        # Merkmal anlegen
PUT    /components/{id}/groups/{gid}/characteristics/{cid}  # Merkmal ändern
DELETE /components/{id}/groups/{gid}/characteristics/{cid}  # Merkmal löschen

Werte

POST   /components/{id}/characteristics/{cid}/values         # Wert anlegen
PUT    /components/{id}/characteristics/{cid}/values         # Alle Werte auf einmal ersetzen
PUT    /components/{id}/characteristics/{cid}/values/{vid}   # Wert ändern
DELETE /components/{id}/characteristics/{cid}/values/{vid}   # Wert löschen

Preise

GET    /components/{id}/characteristics/{cid}/pricelist           # Staffelpreise abrufen
PUT    /components/{id}/characteristics/{cid}/pricelist           # Staffelpreise ersetzen
POST   /components/{id}/characteristics/{cid}/matrix/upload       # Preismatrix als CSV hochladen

Regeln

GET    /components/{id}/rules          # Regeln abrufen
POST   /components/{id}/rules          # Regel anlegen
PUT    /components/{id}/rules/{rid}    # Regel ändern
DELETE /components/{id}/rules/{rid}    # Regel löschen

Versionen und Veröffentlichen

GET    /components/{id}/versions                       # Gespeicherte Versionen
POST   /components/{id}/versions/{version}/restore     # Version als Entwurf wiederherstellen
POST   /components/{id}/publish                        # Entwurf veröffentlichen — Veröffentlichen
GET    /components/{id}/publish/status                 # Fortschritt der Veröffentlichung

Die vollständige Liste mit allen Feldern findest du in der API-Referenz.

Beispiel: Merkmal mit Werten anlegen

Merkmal in Gruppe 5 der Komponente 123 anlegen:

POST /components/123/groups/5/characteristics
Authorization: Bearer DEIN_API_SCHLUESSEL
Content-Type: application/json

{
  "alt_title": "farbe",
  "title": { "de_DE": "Farbe", "en_US": "Colour" },
  "type": "select",
  "is_required": "1"
}

Die Antwort enthält die ID des neuen Merkmals (hier 42). Danach alle Werte auf einmal setzen:

PUT /components/123/characteristics/42/values
Authorization: Bearer DEIN_API_SCHLUESSEL
Content-Type: application/json

{
  "values": [
    { "title": { "de_DE": "Weiß" },           "value": "weiss",      "price": 0 },
    { "title": { "de_DE": "Anthrazit" },      "value": "anthrazit",  "price": 15.00 },
    { "title": { "de_DE": "RAL Sonderlack" }, "value": "ral",        "price": 45.00 }
  ]
}

alt_title ist der interne Name des Merkmals (nur Buchstaben, Ziffern und _) — über ihn sprichst du das Merkmal in Formeln an. Texte wie title sind Objekte mit einem Eintrag pro Sprache.

Beispiel: Preismatrix hochladen

POST /components/123/characteristics/77/matrix/upload
Authorization: Bearer DEIN_API_SCHLUESSEL
Content-Type: application/json

{
  "name": "Preise 2026",
  "csv": ";500;1000;1500\n500;89;119;149\n1000;129;169;209",
  "delimiter": ";"
}

Die erste Zeile enthält die Werte der X-Achse, die erste Spalte die Werte der Y-Achse. Alternativ lädst du die Datei als multipart/form-data im Feld file hoch. Mehr dazu: Preismatrizen aus Excel/CSV.

Beispiel: Veröffentlichen

POST /components/123/publish
Authorization: Bearer DEIN_API_SCHLUESSEL

Die Veröffentlichung läuft im Hintergrund. Die Antwort 202 Accepted enthält die Adresse, unter der du den Fortschritt abfragst (GET /components/123/publish/status). Der Schlüssel braucht dafür die Berechtigung Veröffentlichen.

Fehlercodes

Vollständige API-Referenz

Alle Endpunkte mit Feldern, Beispielen und Testmöglichkeit direkt im Browser: admin.configento.app/docs/api — auch erreichbar über Einstellungen → API → API-Dokumentation im V3-Backend.

Support

Bei Fragen zur API: Support über den Chat-Button im Service-Portal.

Nächste Schritte

• Globale Einstellungen — API
• Merkmale & Optionen anlegen
• Preismatrizen aus Excel/CSV