GET
/api/mod/productos/{espacio}/catalog/searchBusca en el catálogo
Encuentra variantes por lo que escribe una persona: «café la loma de medio kilo» encuentra «Café molido La Loma 500 g». Busca en el nombre, el SKU y, en consultas cortas, la descripción.
- PERMISOlee (vale cualquier clave)
- CRÉDITOSno gasta
- AUTENTICACIÓNBearer bth_…
PARÁMETROS
| CAMPO | TIPO | REQUERIDO | QUÉ ES |
|---|---|---|---|
| espacio | string | SÍ | El id del espacio (sale en GET /api/companies). Tiene que tener el módulo Productos. |
| q | string, query | SÍ | Lo que se busca, en lenguaje natural. |
| only_active | bool, query | no | Solo productos activos y variantes activas. Por defecto true. |
| limit | int, query | no | Cuántos resultados como mucho. Por defecto 20. |
RESPUESTA 200
Una fila por variante, la que mejor encaja primero.
| CAMPO | TIPO | QUÉ ES |
|---|---|---|
| results[].product_id | string | El producto. |
| results[].variant_id | string | La variante. |
| results[].sku · nombre | string | El SKU y el nombre del producto. |
| results[].estado | string | El estado del producto. |
| results[].option_values | object | Los valores de opción de la variante. |
| results[].via_descripcion | true | Solo si entró por la descripción y no por el nombre o el SKU. |
ERRORES DE ESTA RUTA · SIEMPRE {"detail": …}
| STATUS | CUÁNDO | DETAIL LITERAL |
|---|---|---|
| 403 | El espacio no tiene el módulo Productos | módulo no habilitado para este espacio. |
| 422 | Falta q (detail es una lista) | — |
Y los de cualquier ruta —clave inválida, cuenta no al día, IP, límites—, en Errores, límites y créditos.
CONVIENE SABER
- No distingue tildes ni mayúsculas, entiende plurales («jabones» encuentra «Jabón») y unidades («1 litro» encuentra «1000ml», «medio kilo» no: escribe «500 g»).
- Las palabras que no aparecen en ningún producto no tumban la búsqueda: se ignoran. Si nada encaja, la lista viene vacía.
- Para el precio de lo encontrado, cotiza sus variant_id.