Introducción a la API

La API de Semantico te permite gestionar el enriquecimiento del catálogo desde tus propios sistemas: crear productos, lanzar la generación con IA, hacer seguimiento de los trabajos en segundo plano y recibir los resultados por webhook.

Para consultar la referencia completa de cada endpoint (parámetros, esquemas y ejemplos para probar), consulta la API Reference, que se genera a partir del esquema OpenAPI de Semantico.

URL base

Todos los endpoints se sirven en:

https://api.semantico.ai/api/v1

Todas las peticiones y respuestas usan JSON, salvo que se indique lo contrario.

Autenticación

La mayoría de los endpoints requieren un bearer token:

Authorization: Bearer <token>

Para el acceso programático, usa un token de API de larga duración. Consulta Autenticación para saber cómo obtenerlo y usarlo.

Errores

Semantico usa los códigos de estado HTTP estándar:

Estado	Significado
400 Bad Request	Error de validación (con el detalle por campo en el cuerpo).
401 Unauthorized	Falta el token o no es válido.
403 Forbidden	El token es válido, pero no tiene el permiso o la suscripción necesarios.
404 Not Found	El recurso no existe.
409 Conflict	El recurso ya existe.

Los errores de validación se devuelven por campo:

{
  "field_name": ["Human-readable validation message"]
}

Tu primera llamada

Lista los productos de tu espacio de trabajo:

curl -H "Authorization: Bearer <your-api-token>" \
  https://api.semantico.ai/api/v1/products/

Crea un producto a partir de una referencia:

curl -X POST \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"sku": "SKU-001", "name": "Acme water bottle 750ml"}' \
  "https://api.semantico.ai/api/v1/products/?locale=en-US"

Paginación

Los endpoints de listado están paginados. Usa page (empieza en 1) y page_size (20 por defecto):

curl -H "Authorization: Bearer <your-api-token>" \
  "https://api.semantico.ai/api/v1/products/?page=2&page_size=100"

Los resultados llegan en results y los datos de la página en pagination:

{
  "pagination": {
    "links": {
      "next": "https://api.semantico.ai/api/v1/products/?page=3&page_size=100",
      "previous": "https://api.semantico.ai/api/v1/products/?page=1&page_size=100"
    },
    "total": 1250,
    "page_size": 100,
    "page": 2
  },
  "results": []
}

Para recorrer todo el catálogo, sigue pagination.links.next hasta que valga null.

Secciones personalizadas en el listado de productos

GET /products/ no incluye tus secciones personalizadas por defecto. Para obtenerlas, pasa sus códigos en sections, separados por comas o repitiendo el parámetro:

curl -H "Authorization: Bearer <your-api-token>" \
  "https://api.semantico.ai/api/v1/products/?sections=short_description,colour&locale=es-ES"

Cada producto incluye entonces un objeto sections con una clave por cada código pedido:

{
  "id": 1234,
  "sku": "SKU-001",
  "name": "Botella de agua Acme 750 ml",
  "sections": {
    "short_description": "Botella de acero de 750 ml, sin fugas, que mantiene la bebida fría 24 h.",
    "colour": [
      { "id": 88, "reference": 12, "label": "Azul", "external_id": "blue", "color": "#2563EB", "content": "", "order": 0 }
    ]
  }
}

• Las secciones de texto devuelven un texto. Las de opción única o múltiple devuelven una lista con las opciones seleccionadas.
• Si una sección pedida no tiene contenido para ese producto, vale null.
• El contenido se devuelve en el locale pedido. Las secciones que no se traducen usan el idioma por defecto del espacio de trabajo.

Para saber el código de una sección, consulta cualquier producto con GET /products/{id}/. Cada elemento de su array sections incluye section_definition.code.

Filtrar por el valor de una sección

Añade una condición después del código para incluir la sección y filtrar el listado por ella:

Valor	Devuelve los productos en los que la sección…
code	(sin filtro, solo incluye la sección)
code:valor	es igual a valor (sin distinguir mayúsculas)
code:~valor	contiene valor
code:filled	tiene contenido
code:empty	no tiene contenido
code:gt:5	es un número mayor que 5 (también gte, lt, lte, eq)

Por ejemplo, ?sections=short_description:empty,colour devuelve los productos que aún no tienen descripción corta, junto con su color.

Operaciones de larga duración

La generación, las subidas de CSV y las sincronizaciones con tiendas se ejecutan en segundo plano. Estos endpoints responden de inmediato con un task_id (o background_task_id). Consulta periódicamente los endpoints de tareas en segundo plano para seguir el progreso, o configura un webhook para recibir un aviso cuando termine cada producto.

Siguientes pasos

• Autenticación: obtén y usa un token de API.
• Webhooks: recibe los resultados de la generación a medida que terminan.
• API Reference: todos los endpoints en detalle.