Convenciones de la API

Esta página resume las reglas comunes a todos los endpoints de la External Integrations API. Si tu integración no respeta estas convenciones, recibirás 400 Bad Request, 401 Unauthorized, o errores estructurados.

Base URLs

Entorno	Base URL	Cuándo
Producción	https://api.neuroon.ai	Tráfico real, datos persistentes, conversiones que cuentan
Desarrollo	https://dev-api.neuroon.ai	Pruebas de integración, payloads de error, edge cases sin riesgo

Las claves API emitidas en Desarrollo no funcionan contra Producción y viceversa. Usa variables de entorno separadas:

NEUROON_API_URL=https://api.neuroon.ai
NEUROON_API_KEY=tu_api_key_aqui

Ver Cambiar de entorno para configuración por stack.

Formato

• Request body: JSON con Content-Type: application/json; charset=utf-8. camelCase en todos los campos.
• Response body: JSON camelCase. Las claves siempre son strings; los números pueden ser int, long, decimal (precios). Las fechas son ISO 8601 (2026-05-06T10:15:00Z o sin Z si es local — el backend devuelve UTC sin offset).
• Charset: UTF-8 obligatorio. El backend rechaza latin-1 con 400.

JSON estricto

PascalCase, snake_case o claves con espacios serán ignoradas o producirán 400 Validation failed. Usa JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase } en .NET o equivalente en tu stack.

Headers obligatorios

Header	Aplica a	Valor
Content-Type	requests con body	application/json
Accept	recomendado	application/json
Authorization	todos los endpoints	Bearer <api-key>

Headers opcionales útiles:

• Accept-Language: es-ES, en-US, fr-FR, etc. — el backend usa este valor para textos generados si encaja con uno de los idiomas soportados; si no, cae a es.
• User-Agent: TuApp/1.2.3 — para tu propio análisis en logs (recomendado).

Autenticación

Todas las llamadas a /api/integrations/v1/* requieren:

Authorization: Bearer <api-key>

La API key se obtiene desde el dashboard de Neuroon (shop settings) y está vinculada a una tienda específica. No necesitas incluir shopId en la URL — el backend resuelve la tienda a partir de la API key.

Ver Autenticación · Visión general para más detalles.

Idempotencia

• POST /api/integrations/v1/products/sync es idempotente por externalId: enviar el mismo externalId dos veces actualiza el producto, no duplica. Esto incluye el modo INCREMENTAL. El modo FULL reemplaza el catálogo completo — úsalo solo en migraciones iniciales.
• POST /api/integrations/v1/conversions acepta orderId único por shop; un segundo POST con el mismo orderId se ignora silenciosamente.
• Los demás endpoints son GET (sin efectos), PUT (actualización), DELETE (borrado) o stateless.

Latencia y consistencia

• Indexación de productos: 2-5 segundos tras 200 OK en products/sync. El producto no es buscable inmediatamente. Si tu test de integración hace GET /products/by-external/{id} justo después del sync, espera ~5 s o pollea con backoff.
• Cuotas: totalProducts y searchesLimit en GET /shop se cachean ~5 min en algunos consumidores. El backend siempre devuelve el dato actualizado.

Estructura de error

Todos los errores siguen un formato uniforme con error y message. Los errores de validación incluyen detalles field-level.

Rate limits

Basados en el plan de suscripción. Headers de respuesta: X-RateLimit-Limit, X-RateLimit-Remaining. En 429, también Retry-After (segundos).

Paginación

GET /api/integrations/v1/products acepta:

• page (0-indexed, default 0)
• size (default 20, máximo 100)
• sort (formato property,asc|desc, ej. name,asc)

CORS

• /api/widget/*: CORS abierto a cualquier origen (es JS desde navegadores de clientes).
• /api/integrations/*: CORS deshabilitado por diseño — son llamadas server-to-server. Si llamas desde un navegador, el backend rechazará la petición.

Si tu integración server-to-server pasa por un proxy que añade Origin automáticamente y rompe la validación, configura el proxy para no enviar el header.

Próximas lecturas

• API · Visión general
• Autenticación · Visión general — qué credencial usar.
• Referencia (Try it) — playground interactivo.