Migración desde la documentación antigua
La documentación anterior contenía afirmaciones que no se correspondían con la implementación real de Neuroon. Esta página enumera esas discrepancias y mapea las URLs viejas a las nuevas. La hemos publicado como página propia para que cualquier integración basada en la docu antigua pueda corregirse de forma sistemática.
Lo que la docu antigua decía → realidad
| Tema | Docu antigua | Realidad actual |
|---|---|---|
| Generación de Widget Token | Endpoint REST con respuesta wt_… opaco | El token lo firma tu propio servidor localmente con la Shop API Key como secreto HMAC. TTL 24 h. Ver Widget Token |
| Distribución del widget | npm install @neuroon/widget | Sólo CDN versionado con SRI. El paquete del repo no se publica al registry. Ver Qué no está soportado |
| API global del widget | window.NeuroonWidget.search, .clearResults, .triggerQuery | No existen. Sí existen init, getInstance, destroy, setTheme, setStyles y los hooks de token (onTokenExpiring, onTokenRefreshed). Ver Widget · Instalación |
| Callbacks JS | onSearch, onResultClick, onFilterChange, onError como puntos de extensión | No existen como callbacks públicos. Para reaccionar a actividad del widget, usa los CustomEvents del DOM |
| SDKs oficiales | "SDK PHP", "SDK Python", "SDK Ruby" | No existen SDKs oficiales. Cualquier cliente HTTP + JSON |
| Versionado API | /v1/, /v2/ | No hay versionado en la URL. Compat por contrato |
| Origin validation | No documentada | Sí existe: 403 Origin mismatch para navegadores; "no Origin = allow" para clientes server-to-server |
| Sync máximo | "10 000 productos por request" | 500 productos por request (límite del backend) |
| Sync FULL vs INCREMENTAL | No diferenciados | INCREMENTAL (upsert por externalId, recomendado) vs FULL (borra el índice + reinserta) |
| Indexación | "Inmediata tras 200 OK" | Eventual consistency: 2–5 segundos para que el producto sea buscable |
| Idiomas del widget | "12 idiomas" | 9 (es, en, fr, de, it, pt, ca, eu, gl). es y en eager; resto lazy |
| Tema | Sólo dark | Dual: dark + light, con 30+ CSS vars --nrn-* (formato RGB-triplet, --nrn-primary: 6 182 212) |
Mapeo de URLs
URLs viejas que ya no existen. Cada una redirige (o debería redirigir) al nuevo destino:
| URL antigua | Nuevo destino | Estado |
|---|---|---|
/getting-started | /get-started/quickstart | Vigente con redirect |
/widget/install | /widget/installation/script-tag | Vigente con redirect |
/widget/advanced/javascript-api | /get-started/whats-not-supported#control-imperativo-de-la-búsqueda-desde-js | Reformulado |
/widget/callbacks | /get-started/whats-not-supported#callbacks-js-públicos | Removed |
/widget/hooks | /get-started/whats-not-supported#callbacks-js-públicos | Removed |
/api/auth/hmac | /authentication/widget-token | Renombrado (sigue siendo HMAC, ahora documentado como Widget Token) |
/api/sdks/php | /get-started/whats-not-supported#sdks-oficiales | Removed |
/api/sdks/python | /get-started/whats-not-supported#sdks-oficiales | Removed |
/api/webhooks/outbound | /get-started/whats-not-supported#webhooks-salientes | Removed |
/api/v1/* | /api/* | Renombrado (no hay versionado en URL) |
/integrations/wordpress-plugin | WordPress | Vigente |
Anclas para redirects
Estas anclas existen en Qué no está soportado específicamente para que los redirects desde las URLs antiguas tengan un destino útil:
#paquete-npm-del-widget#sdks-oficiales#webhooks-salientes#control-imperativo-de-la-búsqueda-desde-js#callbacks-js-públicos#versionado-de-la-api-http
¿Por qué cambió todo esto?
La documentación anterior se construyó en paralelo con prototipos que nunca llegaron a producción. Cuando el producto evolucionó, partes de la documentación quedaron describiendo aspiraciones en vez de implementación real. Esta versión, etiquetada con verified_at: 2026-05-06, se ha verificado contra el código fuente: cada afirmación técnica enlaza al path:line que la respalda.
Si encuentras una discrepancia adicional, abre un ticket a Soporte y la corregimos.
Próximas lecturas
- Qué no está soportado — la lista canónica de capacidades inexistentes.
- Changelog — historial de cambios.
- Quickstart — la integración real, en 5 pasos.