API — Introducción

Última actualización: 19. octubre 2026

Con la API de configento.app usted gestiona sus componentes desde otros sistemas: leer, crear y modificar grupos, características, valores, reglas, precios escalonados y matrices de precios, y publicar los cambios. Los usos típicos son un PIM o ERP que transfiere valores y precios, o un script que ajusta muchos componentes a la vez.

Este artículo muestra los primeros pasos. Todos los endpoints con todos sus campos están en la referencia de la API.

Qué puede hacer la API y qué no

La API trabaja con los mismos datos que el editor del admin. Lo que usted crea allí también puede crearlo a través de la API, y viceversa.

No es posible a través de la API:

Gestionar claves de API, comprar tokens de IA y leer o renovar las credenciales de las integraciones de tienda: eso queda reservado al admin.
Webhooks: configento.app no avisa a su sistema de los cambios. Si quiere detectar cambios, consulte las versiones de un componente (vea Versiones).
Leer el estado publicado: la API devuelve siempre el borrador, es decir, lo que hay en ese momento en el editor. Vea Borrador y publicación.

La referencia también lista endpoints bajo /storefront/…, /plugin/… y /webhooks/…. Los usan los plugins de tienda y el portal de servicio con sus propias credenciales; con una clave de API no puede llamarlos.

Crear una clave de API

Cada solicitud necesita una clave de API. La crea en el admin en Ajustes → API:

Introduzca un Nombre de la clave, p. ej. «PIM» o «Sincronización ERP».
Elija el Permiso: Solo lectura o Lectura y escritura.
Con Lectura y escritura, marque opcionalmente Publicar y/o IA.
Opcionalmente, indique una fecha en Válida hasta (opcional).
Haga clic en Crear. La clave se muestra una sola vez: cópiela de inmediato y guárdela en un lugar seguro.

Importante:

Una clave pertenece a la service order en la que la creó y solo funciona con los componentes de esta. La lista Claves activas muestra solo las claves de esta service order.
Una clave actúa en su nombre. Si pierde el acceso a la service order, por ejemplo porque le retiran del equipo, sus claves responden con 403.
Con fecha de caducidad, una clave funciona hasta el final de ese día (hora alemana) y después responde con 401. Con Cambiar puede aplazar o eliminar la fecha; así, también una clave caducada vuelve a ser válida.
Revocar bloquea una clave de inmediato.
Lo mejor es crear una clave por integración. Así podrá revocar una sola sin afectar a las demás.

Más sobre la pestaña API: Configuración global.

Permisos

Permiso	Permite
Solo lectura	Solo solicitudes `GET`. Todo lo demás responde con `403` «This API key is read-only.»
Lectura y escritura	Además, crear, modificar y eliminar borradores: componentes, grupos, características, valores, reglas, precios escalonados, matrices de precios, etiquetas
+ Publicar	Además, publicar componentes (`POST /components/{id}/publish`) y eliminarlos (`DELETE /components/{id}`); ambas acciones afectan de inmediato a la tienda
+ IA	Además, usar el asistente IA a través de la API (`/ai/…`); esto consume tokens de IA

Publicar e IA solo están disponibles junto con Lectura y escritura; al crear la clave, ambas están desactivadas. Así, por ejemplo, un PIM puede mantener valores y precios en el borrador mientras una persona revisa y publica en el admin. Si cambia los permisos de una clave, se aplican desde la siguiente solicitud.

URL base y cabeceras

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

Cada solicitud envía la clave como token Bearer:

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

La primera llamada

Listar los componentes:

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

La respuesta contiene solo los datos básicos de cada componente:

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

Leer un componente completo, con grupos, características, valores y reglas:

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

El modelo de datos

Componente
├── groups[]                 Grupos
│   └── characteristics[]    Características
│       └── values[]         Valores
├── rules[]                  Reglas
└── rulesgroups[]            Grupos de reglas

Nombre interno: cada característica tiene su nombre interno en alt_title (solo letras, cifras y _). Con él se refiere a la característica en las fórmulas.
Textos por idioma: las denominaciones como title son objetos con una entrada por idioma, p. ej. { "de_DE": "Farbe", "en_US": "Colour" }. Las claves son los códigos de idioma de su componente.
ID: los ID de grupos y características solo valen dentro de un componente. Por eso todas las rutas están bajo /components/{id}/….

Borrador y publicación

Todo va al borrador. Cada solicitud de escritura modifica el borrador, igual que guardar en el editor. Su tienda no ve nada hasta que se publica el componente.
La lectura devuelve el borrador. GET /components/{id} muestra el borrador actual, no el estado que funciona en la tienda.
Cada cambio es una versión. Cada solicitud de escritura crea una nueva versión. Para muchos cambios a la vez, use por eso los endpoints agrupados (p. ej. todos los valores de una característica en una solicitud) en lugar de muchas llamadas individuales.
ID negativos: un componente que nunca se ha publicado tiene un ID negativo (p. ej. -4). Al publicarlo por primera vez recibe un ID positivo. A partir de entonces solo vale el nuevo ID; tómelo de la consulta de estado (final_component_id).

Los endpoints más importantes

Componentes

GET    /components                     # Todos los componentes (datos básicos)
GET    /components/{id}                # Componente con grupos, características, valores, reglas
POST   /components                     # Crear un componente vacío
PUT    /components/{id}                # Cambiar los datos básicos del componente
POST   /components/{id}/duplicate      # Copiar un componente (como nuevo borrador)
DELETE /components/{id}                # Eliminar un componente, ¡también en la tienda! Requiere «Publicar»

POST /components espera title como texto y, opcionalmente, default_locale (por defecto de_DE). La respuesta contiene el nuevo ID, negativo.

Grupos y características

POST   /components/{id}/groups                              # Crear un grupo
PUT    /components/{id}/groups/{gid}                        # Modificar un grupo
DELETE /components/{id}/groups/{gid}                        # Eliminar un grupo
POST   /components/{id}/groups/{gid}/characteristics        # Crear una característica
PUT    /components/{id}/groups/{gid}/characteristics/{cid}  # Modificar una característica
DELETE /components/{id}/groups/{gid}/characteristics/{cid}  # Eliminar una característica

Valores

POST   /components/{id}/characteristics/{cid}/values         # Crear un valor
PUT    /components/{id}/characteristics/{cid}/values         # Sustituir todos los valores a la vez
PUT    /components/{id}/characteristics/{cid}/values/{vid}   # Modificar un valor
DELETE /components/{id}/characteristics/{cid}/values/{vid}   # Eliminar un valor

Precios

GET    /components/{id}/characteristics/{cid}/pricelist        # Leer precios escalonados
PUT    /components/{id}/characteristics/{cid}/pricelist        # Sustituir precios escalonados
POST   /components/{id}/characteristics/{cid}/matrix/upload    # Añadir una tabla a una matriz de precios
DELETE /components/{id}/characteristics/{cid}/matrix/values    # Eliminar todas las tablas de una matriz de precios

Reglas

GET    /components/{id}/rules                # Leer reglas
POST   /components/{id}/rules                # Crear una regla
PUT    /components/{id}/rules/{rid}          # Modificar una regla
DELETE /components/{id}/rules/{rid}          # Eliminar una regla
GET    /components/{id}/rulesgroups          # Leer grupos de reglas

El tipo de regla lo determina validation_type: blacklist, predefine_values (valores predefinidos) o error (error). Más sobre los tipos de regla: Crear un conjunto de reglas.

Versiones y publicación

GET    /components/{id}/versions                     # Versiones, la más reciente primero
POST   /components/{id}/versions/{version}/restore   # Restaurar una versión como borrador
GET    /components/{id}/validate                     # Comprobar si el borrador se puede publicar
POST   /components/{id}/publish                      # Publicar el borrador; requiere «Publicar»
GET    /components/{id}/publish/status               # Progreso de la publicación

Ejemplo: crear una característica con valores

Crear la característica «Color» en el grupo 5 del componente 123:

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

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

La respuesta es la nueva característica con su id (aquí 42). Después cree los valores nuevos uno a uno; cada uno recibe así su ID:

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

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

value es el valor que ven las fórmulas, las reglas y el carrito; price es el recargo.

Puede actualizar los valores existentes en una sola solicitud, p. ej. precios nuevos procedentes del PIM. Para ello, envíe la lista completa con el id de cada valor:

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

Atención: esta solicitud sustituye todos los valores de la característica. Los valores que falten en la lista se eliminan. No omita el id: los valores sin ID no se pueden usar en reglas ni en valores predefinidos. Obtenga los ID antes con GET /components/123.

Ejemplo: subir una matriz de precios

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

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

La primera fila contiene los valores del eje X y la primera columna, los del eje Y. La característica debe ser del tipo matriz de precios (matrixvalue). También puede subir un archivo CSV de hasta 2 MB como multipart/form-data en el campo file.

La subida añade otra tabla; las tablas existentes se conservan. Si quiere sustituir una tabla, elimine antes todas con DELETE …/matrix/values y vuelva a subirla. Más información: Matrices de precios desde Excel/CSV.

Ejemplo: publicar

POST /components/123/publish
Authorization: Bearer SU_CLAVE_API

Antes, el servidor comprueba el borrador. Si tiene errores, recibe de inmediato 422 con los errores en message. Si no, la publicación se ejecuta en segundo plano, y la respuesta 202 Accepted contiene en job_status_url la dirección para la consulta de estado:

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

El campo state pasa por queued, uploading y pushing y termina en done o failed. Con done, final_component_id contiene el ID del componente publicado; en una primera publicación es el nuevo ID positivo.

Códigos de error

Los errores llegan como JSON con un mensaje en message, p. ej. {"message": "Unauthenticated."}. Con datos no válidos, errors indica además los campos afectados.

Estado	Significado
`401`	Clave ausente, no válida, revocada o caducada
`403`	La clave no tiene permiso, p. ej. «This API key is read-only.», «This API key may not publish or delete components.» o un endpoint que solo funciona en el admin. También: ya no tiene acceso a la service order de la clave
`404`	El componente, grupo, característica o valor no existe, o pertenece a otra service order
`409`	Ya hay una publicación en curso para este componente
`422`	Datos no válidos, o el borrador tiene errores que impiden publicar
`429`	Demasiadas solicitudes al asistente IA (como máximo 20 por minuto)

La referencia de la API

Todos los endpoints con campos y ejemplos están en admin.configento.app/docs/api; en el admin, también en Ajustes → API → Documentación de la API. Allí puede probar solicitudes directamente: abra un endpoint, elija Send API Request a la derecha y pegue su clave en la sección Auth.

La referencia está en inglés y usa los términos ingleses: component (componente), group (grupo), characteristic (característica), value (valor), rule (regla).

Próximos pasos

← Todos los artículos Prueba gratuita 14 días