Reference · Modelos de datos

Esta página enumera los DTOs públicos de Neuroon: el contrato que firma el widget contra la API. Los tipos canónicos del widget están y los del backend.

Product

Producto tal como lo recibe el widget desde SearchResponse.results[].

Campo	Tipo	Requerido	Notas
id	string	sí	UUID Neuroon.
shopId	string	sí	UUID del shop.
shopName	string	sí	Nombre del shop.
name	string	sí	Nombre del producto.
description	string	no
price	number	sí	Precio regular.
salePrice	number	no	Si presente, calcula descuento.
currency	string	sí	ISO 4217.
url	string	sí	URL final (host).
imageUrl	string	no
categories	string[]	sí
tags	string[]	sí
brands	string[]	sí
inStock	boolean	sí
score	number	no	Score interno de relevancia (debug).
rating	number	no	0-5.
reviewCount	number	no
stockCount	number	no	Si ≤ 5, el widget muestra badge "Pocas unidades".
externalId	string	no	ID del host (WC post_id, etc.) usado para conversion tracking.
badge	enum	no	BESTSELLER | TRENDING | TOP_RATED.
aiReason	string	no	Razón conversacional ("ideal para asfalto").
aiScore	number	no	Score IA del re-ranker.

Product (catálogo) vs PluginProductDTO (sync)

Product es lo que el widget consume al leer del catálogo. Cuando escribes productos vía POST /api/integrations/v1/products/sync, el shape es PluginProductDTO — más amplio (incluye isActive, parentProductId, attributes, variants, etc.) y serializado por el backend. Ver API → Plugin Sync para el shape completo.

SearchResponse

Respuesta canónica de GET /api/widget/search y POST /api/widget/search. Tipo.

Campo	Tipo	Requerido	Notas
query	string	sí	Query normalizada tras post-process.
results	Product[]	sí
total	number	sí	Total de productos que cumplen filtros.
searchLogId	string	sí	Identificador del turno (attribution).
queryTimeMs	number	sí	Latencia del backend.
intentId	string	no	Detección de intent.
conversationId	string	no	Continuación entre turnos.
isNewConversation	boolean	no	true si arrancó conversación.
turnNumber	number	no	1, 2, 3…
filtersApplied	FiltersApplied	no	Filtros aplicados al ranking.
availableFilters	AvailableFilters	no	Drawer de filtros.
guidedFilters	GuidedFilter[]	no	Preguntas dinámicas.
querySuggestions	QuerySuggestion[]	no	Refinamientos sugeridos.
topProducts	TopProduct[]	no	Carrusel destacado.
aiResponse	string	no	Texto conversacional.
comparison	ComparisonResponse	no
clarification	ClarificationResult	no
buyersGuide	BuyersGuide	no
kit	ProductKit	no
followUp	FollowUpResponse	no
recommendations	RecommendationsResponse	no
cartAction	CartAction	no	Acción solicitada al widget.
quickReplies	QuickReply[]	no	Chips de respuesta rápida.
responseLanguage	string	no	ISO del idioma del agente (es, en…).

CartState

interface CartState {
  items: CartItem[]
  totalItems: number
  subtotal: string   // formateado por el host: "232,48 €"
  total: string      // formateado por el host
  currency: string   // ISO 4217
  shipping?: CartShippingInfo
}

Campo CartItem	Tipo	Requerido	Notas
key	string	sí	Identificador único del item en el carrito.
id	string	sí	productId Neuroon.
externalId	string	no	ID del host (WC post_id).
name	string	sí
price	string	sí	Formateado por el host.
quantity	number	sí
image	string	no
url	string	no
variant	string	no	"Talla: 42, Color: Negro".
maxQuantity	number	no

CartShippingInfo añade freeShippingThreshold, currentAmount, delta, thresholdMet, destinationCountry, availableCountries[], formattedThreshold y formattedDelta. Ver cart-integration para el flujo.

Event (analytics)

Campo	Tipo	Requerido	Notas
type	string	sí	snake_case (category_click, kit_view…).
searchLogId	string	recomendado	Vincula con turno de búsqueda.
metadata	object	no	Pares libres (sin PII).
timestamp	string ISO-8601	no	Si se omite, lo pone el backend.

CartAction

type CartActionType = 'REMOVE' | 'UPDATE_QUANTITY' | 'ADD_SUGGESTION' | 'CLEAR' | 'SET_DESTINATION_COUNTRY'

interface CartAction {
  type: CartActionType
  productId?: string
  externalProductId?: string
  externalId?: string             // alias legacy
  itemKey?: string
  newQuantity?: number
  countryCode?: string             // ISO-3166-1 alpha-2 mayúsculas
  confirmationPrompt?: string
  product?: CartActionProduct      // sólo en ADD_SUGGESTION
}

Suggestion

interface Suggestion {
  type: 'query' | 'category' | 'brand' | 'product'
  text: string
  count?: number
  icon?: string
  product?: Product
}

GuidedFilter

interface GuidedFilter {
  id: string
  question: string
  type: 'SINGLE_CHOICE' | 'MULTI_CHOICE' | 'RANGE'
  priority: number
  options: FilterOptionDTO[]
}

interface FilterOptionDTO {
  label: string
  filter: Record<string, unknown>
  count?: number
  isSelected?: boolean
  isRecommended?: boolean
  detectionSource?: 'QUERY_ANALYSIS' | 'TRENDING' | 'INTENT_BASED'
  detectionReason?: string
}

Próximas lecturas

• Reference → Errores
• Reference → Variables CSS
• Reference → Bus de eventos
• Widget → Eventos