API — Introduction

Dernière mise à jour: 19. octobre 2026

Avec l'API configento.app, vous gérez vos composants depuis d'autres systèmes : lire, créer et modifier des groupes, caractéristiques, valeurs, règles, prix échelonnés et matrices de prix – et publier vos modifications. Les usages typiques sont un PIM ou un ERP qui transmet des valeurs et des prix, ou un script qui adapte de nombreux composants à la fois.

Cet article présente les premiers pas. Tous les endpoints avec l'ensemble de leurs champs se trouvent dans la référence de l'API.

Ce que l'API sait faire – et ce qu'elle ne fait pas

L'API travaille avec les mêmes données que l'éditeur de l'administration. Ce que vous y créez, vous pouvez aussi le créer via l'API, et inversement.

Impossible via l'API :

Gérer les clés API, acheter des jetons IA et lire ou renouveler les identifiants des intégrations boutique – cela reste réservé à l'administration.
Webhooks : configento.app n'informe pas votre système des modifications. Pour détecter des modifications, interrogez les versions d'un composant (voir Versions).
Lire l'état publié : l'API renvoie toujours le brouillon – c'est-à-dire ce qui se trouve actuellement dans l'éditeur. Voir Brouillon et publication.

La référence liste aussi des endpoints sous /storefront/…, /plugin/… et /webhooks/…. Ils sont utilisés par les plugins boutique et le portail de service avec leurs propres identifiants ; vous ne pouvez pas les appeler avec une clé API.

Créer une clé API

Chaque requête nécessite une clé API. Vous la créez dans l'administration sous Paramètres → API :

Saisissez un Nom de la clé, par ex. « PIM » ou « Synchro ERP ».
Choisissez l'Autorisation – Lecture seule ou Lecture et écriture.
Avec Lecture et écriture, cochez si besoin Publier et/ou IA.
Définissez si besoin une date sous Valable jusqu'au (facultatif).
Cliquez sur Créer. La clé n'est affichée qu'une seule fois – copiez-la immédiatement et conservez-la en lieu sûr.

Important :

Une clé appartient à la service order dans laquelle vous l'avez créée et ne fonctionne qu'avec les composants de celle-ci. La liste Clés actives n'affiche que les clés de cette service order.
Une clé agit en votre nom. Si vous perdez l'accès à la service order – par exemple parce que vous êtes retiré de l'équipe –, vos clés répondent par 403.
Avec une date d'expiration, une clé fonctionne jusqu'à la fin de ce jour (heure allemande), puis répond par 401. Avec Modifier, vous décalez ou supprimez la date – une clé expirée redevient ainsi valable.
Révoquer bloque une clé immédiatement.
Créez de préférence une clé par intégration. Vous pourrez ainsi en révoquer une seule sans gêner les autres.

Plus d'informations sur l'onglet API : Paramètres globaux.

Autorisations

Autorisation	Permet
Lecture seule	Uniquement les requêtes `GET`. Tout le reste répond par `403` « This API key is read-only. »
Lecture et écriture	En plus : créer, modifier et supprimer des brouillons – composants, groupes, caractéristiques, valeurs, règles, prix échelonnés, matrices de prix, tags
+ Publier	En plus : publier des composants (`POST /components/{id}/publish`) et les supprimer (`DELETE /components/{id}`) – les deux agissent immédiatement dans la boutique
+ IA	En plus : utiliser l'assistant IA via l'API (`/ai/…`) – cela consomme des jetons IA

Publier et IA ne sont disponibles qu'avec Lecture et écriture ; les deux sont désactivés à la création. Ainsi, par exemple, un PIM peut gérer valeurs et prix dans le brouillon pendant qu'une personne vérifie et publie dans l'administration. Si vous modifiez les autorisations d'une clé, elles s'appliquent dès la requête suivante.

URL de base et en-têtes

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

Chaque requête envoie la clé comme jeton Bearer :

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

Le premier appel

Lister les composants :

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

La réponse ne contient que les données clés de chaque composant :

{
  "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
}

Lire un composant complet – avec groupes, caractéristiques, valeurs et règles :

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

Le modèle de données

Composant
├── groups[]                 Groupes
│   └── characteristics[]    Caractéristiques
│       └── values[]         Valeurs
├── rules[]                  Règles
└── rulesgroups[]            Groupes de règles

Nom interne : chaque caractéristique porte son nom interne dans alt_title (lettres, chiffres et _ uniquement). C'est par lui que vous désignez la caractéristique dans les formules.
Textes par langue : les libellés comme title sont des objets avec une entrée par langue, par ex. { "de_DE": "Farbe", "en_US": "Colour" }. Les clés sont les codes de langue de votre composant.
ID : les ID de groupes et de caractéristiques ne valent qu'à l'intérieur d'un composant. C'est pourquoi tous les chemins se trouvent sous /components/{id}/….

Brouillon et publication

Tout va dans le brouillon. Chaque requête d'écriture modifie le brouillon – exactement comme l'enregistrement dans l'éditeur. Votre boutique n'en voit rien tant que le composant n'est pas publié.
La lecture renvoie le brouillon. GET /components/{id} affiche le brouillon actuel, pas l'état en ligne dans la boutique.
Chaque modification est une version. Chaque requête d'écriture crée une nouvelle version. Pour de nombreuses modifications à la fois, utilisez donc les endpoints groupés (par ex. toutes les valeurs d'une caractéristique en une requête) plutôt que de nombreux appels individuels.
ID négatifs : un composant qui n'a jamais été publié a un ID négatif (par ex. -4). Lors de la première publication, il reçoit un ID positif. À partir de là, seul le nouvel ID est valable – reprenez-le de la requête de statut (final_component_id).

Les endpoints les plus importants

Composants

GET    /components                     # Tous les composants (données clés)
GET    /components/{id}                # Composant avec groupes, caractéristiques, valeurs, règles
POST   /components                     # Créer un nouveau composant vide
PUT    /components/{id}                # Modifier les données clés du composant
POST   /components/{id}/duplicate      # Copier un composant (comme nouveau brouillon)
DELETE /components/{id}                # Supprimer un composant – aussi dans la boutique ! Requiert « Publier »

POST /components attend title sous forme de texte et, en option, default_locale (par défaut de_DE). La réponse contient le nouvel ID, négatif.

Groupes et caractéristiques

POST   /components/{id}/groups                              # Créer un groupe
PUT    /components/{id}/groups/{gid}                        # Modifier un groupe
DELETE /components/{id}/groups/{gid}                        # Supprimer un groupe
POST   /components/{id}/groups/{gid}/characteristics        # Créer une caractéristique
PUT    /components/{id}/groups/{gid}/characteristics/{cid}  # Modifier une caractéristique
DELETE /components/{id}/groups/{gid}/characteristics/{cid}  # Supprimer une caractéristique

Valeurs

POST   /components/{id}/characteristics/{cid}/values         # Créer une valeur
PUT    /components/{id}/characteristics/{cid}/values         # Remplacer toutes les valeurs à la fois
PUT    /components/{id}/characteristics/{cid}/values/{vid}   # Modifier une valeur
DELETE /components/{id}/characteristics/{cid}/values/{vid}   # Supprimer une valeur

Prix

GET    /components/{id}/characteristics/{cid}/pricelist        # Lire les prix échelonnés
PUT    /components/{id}/characteristics/{cid}/pricelist        # Remplacer les prix échelonnés
POST   /components/{id}/characteristics/{cid}/matrix/upload    # Ajouter un tableau à une matrice de prix
DELETE /components/{id}/characteristics/{cid}/matrix/values    # Supprimer tous les tableaux d'une matrice de prix

Règles

GET    /components/{id}/rules                # Lire les règles
POST   /components/{id}/rules                # Créer une règle
PUT    /components/{id}/rules/{rid}          # Modifier une règle
DELETE /components/{id}/rules/{rid}          # Supprimer une règle
GET    /components/{id}/rulesgroups          # Lire les groupes de règles

Le type de règle est défini par validation_type : blacklist, predefine_values (valeurs prédéfinies) ou error (erreur). Plus d'informations sur les types de règles : Créer un jeu de règles.

Versions et publication

GET    /components/{id}/versions                     # Versions, la plus récente d'abord
POST   /components/{id}/versions/{version}/restore   # Restaurer une version comme brouillon
GET    /components/{id}/validate                     # Vérifier si le brouillon peut être publié
POST   /components/{id}/publish                      # Publier le brouillon – requiert « Publier »
GET    /components/{id}/publish/status               # Avancement de la publication

Exemple : créer une caractéristique avec des valeurs

Créer la caractéristique « Couleur » dans le groupe 5 du composant 123 :

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

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

La réponse est la nouvelle caractéristique avec son id (ici 42). Vous créez ensuite les nouvelles valeurs une par une – chacune reçoit ainsi son ID :

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

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

value est la valeur que voient les formules, les règles et le panier ; price est le supplément.

Vous pouvez mettre à jour les valeurs existantes en une seule requête, par ex. de nouveaux prix issus du PIM. Envoyez pour cela la liste complète avec l'id de chaque valeur :

PUT /components/123/characteristics/42/values
Authorization: Bearer VOTRE_CLE_API
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 }
  ]
}

Attention : cette requête remplace toutes les valeurs de la caractéristique. Les valeurs absentes de la liste sont supprimées. N'omettez pas l'id – les valeurs sans ID ne peuvent pas être ciblées dans les règles et les valeurs prédéfinies. Récupérez les ID au préalable avec GET /components/123.

Exemple : téléverser une matrice de prix

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

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

La première ligne contient les valeurs de l'axe X, la première colonne celles de l'axe Y. La caractéristique doit être de type matrice de prix (matrixvalue). Vous pouvez aussi téléverser un fichier CSV de 2 Mo maximum en multipart/form-data dans le champ file.

Le téléversement ajoute un tableau supplémentaire – les tableaux existants sont conservés. Pour remplacer un tableau, supprimez d'abord tous les tableaux avec DELETE …/matrix/values, puis téléversez à nouveau. Plus d'informations : Matrices de prix depuis Excel/CSV.

Exemple : publier

POST /components/123/publish
Authorization: Bearer VOTRE_CLE_API

Le serveur vérifie d'abord le brouillon. S'il contient des erreurs, vous recevez immédiatement 422 avec les erreurs dans message. Sinon, la publication s'exécute en arrière-plan, et la réponse 202 Accepted contient dans job_status_url l'adresse de la requête de statut :

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

Le champ state passe par queued, uploading et pushing et se termine par done ou failed. Avec done, final_component_id contient l'ID du composant publié – lors d'une première publication, il s'agit du nouvel ID positif.

Codes d'erreur

Les erreurs arrivent en JSON avec un message dans message, par ex. {"message": "Unauthenticated."}. En cas de données invalides, errors indique en plus les champs concernés.

Statut	Signification
`401`	Clé absente, invalide, révoquée ou expirée
`403`	La clé n'a pas le droit – par ex. « This API key is read-only. », « This API key may not publish or delete components. » ou un endpoint qui ne fonctionne que dans l'administration. Aussi : vous n'avez plus accès à la service order de la clé
`404`	Le composant, le groupe, la caractéristique ou la valeur n'existe pas – ou appartient à une autre service order
`409`	Une publication est déjà en cours pour ce composant
`422`	Données invalides, ou le brouillon contient des erreurs qui empêchent la publication
`429`	Trop de requêtes adressées à l'assistant IA (20 par minute au maximum)

La référence de l'API

Tous les endpoints avec leurs champs et des exemples se trouvent sur admin.configento.app/docs/api – dans l'administration également via Paramètres → API → Documentation API. Vous pouvez y tester des requêtes directement : ouvrez un endpoint, choisissez Send API Request à droite et collez votre clé dans la section Auth.

La référence est en anglais et utilise les termes anglais : component (composant), group (groupe), characteristic (caractéristique), value (valeur), rule (règle).

Étapes suivantes

← Tous les articles Essai gratuit 14 jours