API — Einstieg & Übersicht

Zuletzt aktualisiert: 19. Oktober 2026

Mit der configento.app API pflegst du deine Komponenten aus anderen Systemen heraus: Gruppen, Merkmale, Werte, Regeln, Staffelpreise und Preismatrizen lesen, anlegen und ändern – und Änderungen veröffentlichen. Typische Einsätze sind ein PIM oder ERP, das Werte und Preise überträgt, oder ein Skript, das viele Komponenten auf einmal anpasst.

Dieser Artikel zeigt den Einstieg. Alle Endpunkte mit sämtlichen Feldern findest du in der API-Referenz.

Was die API kann – und was nicht

Die API arbeitet mit denselben Daten wie der Editor im Admin. Was du dort anlegst, kannst du auch über die API anlegen, und umgekehrt.

Nicht über die API möglich:

API-Schlüssel verwalten, KI-Tokens kaufen und Zugangsdaten der Shop-Integrationen lesen oder erneuern – das bleibt dem Admin vorbehalten.
Webhooks: configento.app benachrichtigt dein System nicht über Änderungen. Wenn du Änderungen erkennen willst, frag die Versionen einer Komponente ab (siehe Versionen).
Den veröffentlichten Stand lesen: Die API liefert immer den Entwurf – also das, was gerade im Editor steht. Siehe Entwurf und Veröffentlichung.

Die Referenz listet auch Endpunkte unter /storefront/…, /plugin/… und /webhooks/…. Diese nutzen die Shop-Plugins und das Service-Portal mit eigenen Zugangsdaten; mit einem API-Schlüssel kannst du sie nicht aufrufen.

API-Schlüssel erstellen

Jede Anfrage braucht einen API-Schlüssel. Du erstellst ihn im Admin unter Einstellungen → API:

Name des Schlüssels eingeben, z. B. „PIM“ oder „ERP-Sync“.
Berechtigung wählen – Nur lesen oder Lesen & Schreiben.
Bei Lesen & Schreiben optional Veröffentlichen und/oder KI anhaken.
Optional ein Datum unter Gültig bis (optional) 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 der Service Order, in der du ihn erstellt hast, und arbeitet nur mit deren Komponenten. Die Liste Aktive Schlüssel zeigt nur die Schlüssel dieser Service Order.
Ein Schlüssel handelt in deinem Namen. Verlierst du den Zugriff auf die Service Order – etwa weil du aus dem Team entfernt wirst –, antworten deine Schlüssel mit 403.
Mit Ablaufdatum funktioniert ein Schlüssel bis zum Ende dieses Tages (deutsche Zeit) und antwortet danach mit 401. Über Ändern verschiebst oder entfernst du das Datum – auch ein abgelaufener Schlüssel wird so wieder gültig.
Widerrufen sperrt einen Schlüssel sofort.
Lege am besten einen Schlüssel pro Integration an. Dann kannst du einen einzelnen widerrufen, ohne die anderen zu stören.

Mehr zum Reiter API: Globale Einstellungen.

Berechtigungen

Berechtigung	Erlaubt
Nur lesen	Nur `GET`-Anfragen. Alles andere antwortet mit `403` „This API key is read-only.“
Lesen & Schreiben	Zusätzlich Entwürfe anlegen, ändern und löschen: Komponenten, Gruppen, Merkmale, Werte, Regeln, Staffelpreise, Preismatrizen, Tags
+ Veröffentlichen	Zusätzlich Komponenten veröffentlichen (`POST /components/{id}/publish`) und löschen (`DELETE /components/{id}`) – beides wirkt sofort im Shop
+ KI	Zusätzlich den KI-Assistenten über die API nutzen (`/ai/…`) – das verbraucht KI-Tokens

Veröffentlichen und KI gibt es nur zusammen mit Lesen & Schreiben; beim Erstellen sind beide aus. So kann zum Beispiel ein PIM Werte und Preise im Entwurf pflegen, während ein Mensch im Admin prüft und veröffentlicht. Änderst du die Berechtigungen eines Schlüssels, gelten sie ab der nächsten Anfrage.

Basis-URL und Header

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

Jede Anfrage sendet den Schlüssel als Bearer-Token:

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

Der erste Aufruf

Komponenten auflisten:

curl https://admin.configento.app/api/v1/components \
  -H "Authorization: Bearer DEIN_API_SCHLUESSEL" \
  -H "Accept: application/json"

Die Antwort enthält pro Komponente nur die Eckdaten:

{
  "data": [
    { "id": 123, "title": { "de_DE": "Carport" }, "edition": null, "requires_bundle": null, "tags": [] },
    { "id": -4,  "title": { "de_DE": "Terrassendach (neu)" }, "edition": null, "requires_bundle": null, "tags": [] }
  ],
  "sync_running": false
}

Eine Komponente vollständig lesen – mit Gruppen, Merkmalen, Werten und Regeln:

curl https://admin.configento.app/api/v1/components/123 \
  -H "Authorization: Bearer DEIN_API_SCHLUESSEL" \
  -H "Accept: application/json"

Das Datenmodell

Komponente
├── groups[]                 Gruppen
│   └── characteristics[]    Merkmale
│       └── values[]         Werte
├── rules[]                  Regeln
└── rulesgroups[]            Regelgruppen

Interner Name: Jedes Merkmal hat in alt_title seinen internen Namen (nur Buchstaben, Ziffern und _). Über ihn sprichst du das Merkmal in Formeln an.
Texte pro Sprache: Bezeichnungen wie title sind Objekte mit einem Eintrag pro Sprache, z. B. { "de_DE": "Farbe", "en_US": "Colour" }. Die Schlüssel sind die Sprachcodes deiner Komponente.
IDs: Gruppen- und Merkmal-IDs gelten nur innerhalb einer Komponente. Deshalb stehen alle Pfade unter /components/{id}/….

Entwurf und Veröffentlichung

Alles landet im Entwurf. Jede schreibende Anfrage ändert den Entwurf – genau wie Speichern im Editor. Dein Shop sieht davon nichts, bis die Komponente veröffentlicht wird.
Lesen liefert den Entwurf. GET /components/{id} zeigt den aktuellen Entwurf, nicht den Stand, der im Shop läuft.
Jede Änderung ist eine Version. Jede schreibende Anfrage legt eine neue Version an. Für viele Änderungen auf einmal nimm deshalb die Sammel-Endpunkte (z. B. alle Werte eines Merkmals in einer Anfrage) statt vieler Einzelaufrufe.
Negative IDs: Eine Komponente, die noch nie veröffentlicht wurde, hat eine negative ID (z. B. -4). Beim ersten Veröffentlichen bekommt sie eine positive ID. Ab dann gilt nur noch die neue ID – übernimm sie aus der Statusabfrage (final_component_id).

Die wichtigsten Endpunkte

Komponenten

GET    /components                     # Alle Komponenten (Eckdaten)
GET    /components/{id}                # Komponente mit Gruppen, Merkmalen, Werten, Regeln
POST   /components                     # Neue leere Komponente anlegen
PUT    /components/{id}                # Eckdaten der Komponente ändern
POST   /components/{id}/duplicate      # Komponente kopieren (als neuer Entwurf)
DELETE /components/{id}                # Komponente löschen – auch im Shop! Braucht „Veröffentlichen“

POST /components erwartet title als Text und optional default_locale (Standard de_DE). Die Antwort enthält die neue, negative ID.

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         # Einen Wert anlegen
PUT    /components/{id}/characteristics/{cid}/values         # Alle Werte auf einmal ersetzen
PUT    /components/{id}/characteristics/{cid}/values/{vid}   # Einen Wert ändern
DELETE /components/{id}/characteristics/{cid}/values/{vid}   # Einen Wert löschen

Preise

GET    /components/{id}/characteristics/{cid}/pricelist        # Staffelpreise lesen
PUT    /components/{id}/characteristics/{cid}/pricelist        # Staffelpreise ersetzen
POST   /components/{id}/characteristics/{cid}/matrix/upload    # Tabelle an eine Preismatrix anhängen
DELETE /components/{id}/characteristics/{cid}/matrix/values    # Alle Tabellen einer Preismatrix löschen

Regeln

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

Den Regeltyp bestimmt validation_type: blacklist, predefine_values (Wertvorbelegung) oder error (Fehler). Mehr zu den Regeltypen: Regelwerk aufbauen.

Versionen und Veröffentlichen

GET    /components/{id}/versions                     # Versionen, neueste zuerst
POST   /components/{id}/versions/{version}/restore   # Version als Entwurf wiederherstellen
GET    /components/{id}/validate                     # Prüfen, ob der Entwurf veröffentlicht werden kann
POST   /components/{id}/publish                      # Entwurf veröffentlichen – braucht „Veröffentlichen“
GET    /components/{id}/publish/status               # Fortschritt der Veröffentlichung

Beispiel: Merkmal mit Werten anlegen

Merkmal „Farbe“ 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 ist das neue Merkmal mit seiner id (hier 42). Neue Werte legst du dann einzeln an – jeder bekommt dabei seine ID:

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

{ "title": { "de_DE": "Anthrazit" }, "value": "anthrazit", "price": 15.00, "sku": "FARBE-ANT" }

value ist der Wert, den Formeln, Regeln und der Warenkorb sehen; price ist der Aufpreis.

Bestehende Werte kannst du in einer Anfrage aktualisieren, z. B. neue Preise aus dem PIM. Schick dafür die vollständige Liste mit der id jedes Werts mit:

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

{
  "values": [
    { "id": 301, "title": { "de_DE": "Weiß" },      "value": "weiss",     "price": 0 },
    { "id": 302, "title": { "de_DE": "Anthrazit" }, "value": "anthrazit", "price": 19.00 }
  ]
}

Achtung: Diese Anfrage ersetzt alle Werte des Merkmals. Werte, die in der Liste fehlen, werden gelöscht. Lass die id nicht weg – Werte ohne ID lassen sich in Regeln und Vorbelegungen nicht ansprechen. Hol dir die IDs vorher mit GET /components/123.

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. Das Merkmal muss vom Typ Preismatrix (matrixvalue) sein. Alternativ lädst du eine CSV-Datei bis 2 MB als multipart/form-data im Feld file hoch.

Der Upload hängt eine weitere Tabelle an – vorhandene Tabellen bleiben. Willst du eine Tabelle ersetzen, lösche vorher alle mit DELETE …/matrix/values und lade dann neu hoch. Mehr dazu: Preismatrizen aus Excel/CSV.

Beispiel: Veröffentlichen

POST /components/123/publish
Authorization: Bearer DEIN_API_SCHLUESSEL

Vorher prüft der Server den Entwurf. Hat er Fehler, kommt sofort 422 mit den Fehlern in message zurück. Sonst läuft die Veröffentlichung im Hintergrund, und die Antwort 202 Accepted enthält in job_status_url die Adresse für die Statusabfrage:

curl https://admin.configento.app/api/v1/components/123/publish/status \
  -H "Authorization: Bearer DEIN_API_SCHLUESSEL" \
  -H "Accept: application/json"

Das Feld state durchläuft queued, uploading und pushing und endet mit done oder failed. Bei done steht in final_component_id die ID der veröffentlichten Komponente – bei einer ersten Veröffentlichung ist das die neue, positive ID.

Fehlercodes

Fehler kommen als JSON mit einer Meldung in message, z. B. {"message": "Unauthenticated."}. Bei ungültigen Daten nennt errors zusätzlich die betroffenen Felder.

Status	Bedeutung
`401`	Kein, ungültiger, widerrufener oder abgelaufener Schlüssel
`403`	Der Schlüssel darf das nicht – z. B. „This API key is read-only.“, „This API key may not publish or delete components.“ oder ein Endpunkt, der nur im Admin geht. Auch: Du hast keinen Zugriff mehr auf die Service Order des Schlüssels
`404`	Komponente, Gruppe, Merkmal oder Wert gibt es nicht – oder er gehört zu einer anderen Service Order
`409`	Für diese Komponente läuft bereits eine Veröffentlichung
`422`	Ungültige Daten, oder der Entwurf hat Fehler, die das Veröffentlichen verhindern
`429`	Zu viele Anfragen an den KI-Assistenten (höchstens 20 pro Minute)

Die API-Referenz

Alle Endpunkte mit Feldern und Beispielen findest du unter admin.configento.app/docs/api – im Admin auch über Einstellungen → API → API-Dokumentation. Dort kannst du Anfragen direkt ausprobieren: Endpunkt öffnen, rechts Send API Request wählen und im Bereich Auth deinen Schlüssel einfügen.

Die Referenz ist auf Englisch und verwendet die englischen Begriffe: component (Komponente), group (Gruppe), characteristic (Merkmal), value (Wert), rule (Regel).

Nächste Schritte

← Alle Artikel 14 Tage kostenlos testen