Arquitectura

Neuroon vive entre dos puntas de tu integración: el navegador del comprador (donde corre el widget) y tu servidor (donde tienes tu catálogo). Entre ambos hay dos APIs separadas con credenciales distintas para que nunca expongas un secreto en el cliente.

Vista de bloques

Pasa el cursor o haz click sobre un flujo para ver el detalle.

Las dos APIs

API	Prefijo	Quién la llama	Credencial
Widget	/api/widget/*	Tu frontend (navegador del comprador)	X-Widget-Token (TTL 24 h)
Plugin	/api/plugin/shops/*	Tu servidor	X-Shop-API-Key permanente + validación de origen

Ambas comparten el mismo motor de búsqueda. Tu servidor habla siempre HTTPS contra api.neuroon.ai. El comprador nunca ve tu Shop API Key.

Flujo end-to-end resumido

1. El comprador busca: el widget llama a Widget API con su X-Widget-Token. La respuesta incluye productos, filtros guiados y, según plan, la respuesta del asistente.
2. El comprador hace click: el widget envía track/click (idempotente).
3. El comprador compra: tu servidor llama a Plugin API con X-Shop-API-Key para registrar la conversión.
4. Tú actualizas el catálogo: tu servidor llama a Plugin API con products/sync (lotes de hasta 500). El producto es buscable en 2 a 5 segundos.

Eventual consistency

Tras 200 OK en products/sync hay una ventana corta antes de que el producto sea buscable. Si tu test E2E falla buscando un producto recién insertado, espera unos segundos y reintenta con backoff.

Sin versionado en URL

Hoy, la API no expone /v1/, /v2/ en la URL: la compatibilidad va por contrato y los cambios breaking se anuncian en el Changelog. Habrá versionado en URL en el futuro — cuando llegue, será aditivo: las rutas actuales seguirán funcionando.

Próximas lecturas

• Quickstart — del cero a la primera búsqueda en 5 minutos.
• Entornos — Producción vs Desarrollo.
• Autenticación · Visión general — qué credencial usar y cuándo.