Shop API Key

La Shop API Key autentica las llamadas server-to-server contra /api/plugin/shops/*. Sirve para sincronizar el catálogo, registrar conversiones, verificar el dominio y consultar metadatos de la tienda.

Cabecera

X-Shop-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Formato

sk_ seguido de 32 caracteres hexadecimales. Longitud total ~35 caracteres. Es permanente hasta rotación: no caduca por tiempo.

Validación de Origin

El filtro valida la cabecera Origin (o Referer como fallback) contra el dominio registrado en la tienda:

Si el cliente es un navegador y envía Origin, debe coincidir con shop.url. En caso contrario → 403 Forbidden con mensaje Origin mismatch — API Key cannot be used from this domain.
Si el cliente no envía Origin ni Referer (cualquier cliente server-to-server: HttpClient de .NET, requests de Python, axios de Node, cURL, librería HTTP de Java, etc.) → la petición se permite. Es el comportamiento intencionado para integración server-to-server.

Origin validation: tres modos

Cliente	Header `Origin`	Comportamiento
Server-to-server (HttpClient .NET, `requests` Python, cURL, axios Node)	Ausente	Se permite — `X-Shop-API-Key` es la única credencial requerida
Navegador desde `shop.url`	Coincide con `shop.url` (normalizado)	Se permite
Navegador desde otro dominio	Distinto a `shop.url`	`403 Origin mismatch — API Key cannot be used from this domain`

La normalización de URL elimina protocolo, www. y barras finales, así que https://example.com, http://www.example.com/ y example.com se consideran equivalentes.

Nota: el Widget Token (X-Widget-Token, ver Widget Token) usa una matriz de validación distinta — admite además dominios "trusted" (neuroon.ai y subdominios, localhost, 127.0.0.1). Esa lista no aplica a la Shop API Key, que sólo se compara contra shop.url.

Generación y rotación

Desde el Dashboard:

Tienda → API Keys → "Crear nueva clave".
Se muestra una sola vez. Cópiala a tu secret manager.
Para rotar: "Rotar clave" → la antigua queda invalidada al instante.

Almacenamiento

Sitios donde sí debes guardarla:

.NET: User Secrets en desarrollo, Azure Key Vault o appsettings.{Environment}.json montado como secret en producción. Nunca en web.config plano ni hardcodeada.
WordPress: define en wp-config.php (que está fuera del docroot) o en wp_options cifrado.
Generales: AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, GitHub Actions Secrets, Doppler, etc.

Sitios donde nunca debes guardarla:

Repositorios Git (público o privado).
Logs, traces exportadas, mensajes de error visibles al usuario.
Atributos del HTML (data-api-key="...").
Variables JavaScript del navegador.

Ejemplos por stack

cURL

curl -X POST "https://api.neuroon.ai/api/plugin/shops/$SHOP_ID/products/sync" \
-H "X-Shop-API-Key: $NEUROON_API_KEY" \
-H "Content-Type: application/json" \
-d @body.json

Node.js / TypeScript

const res = await fetch(
  `${process.env.NEUROON_API_URL}/api/plugin/shops/${SHOP_ID}/products/sync`,
  {
    method: 'POST',
    headers: {
      'X-Shop-API-Key': process.env.NEUROON_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  },
);

.NET / C# (cualquier .NET 6+)

var apiKey = builder.Configuration["Neuroon:ApiKey"]
             ?? throw new InvalidOperationException("Missing Neuroon:ApiKey");
var apiBase = builder.Configuration["Neuroon:ApiBaseUrl"]
              ?? "https://api.neuroon.ai";

using var client = new HttpClient { BaseAddress = new Uri(apiBase) };
client.DefaultRequestHeaders.Add("X-Shop-API-Key", apiKey);

var response = await client.PostAsJsonAsync(
    $"/api/plugin/shops/{shopId}/products/sync", payload);

response.EnsureSuccessStatusCode();

Python

import os, requests

response = requests.post(
    f"{os.environ['NEUROON_API_URL']}/api/plugin/shops/{SHOP_ID}/products/sync",
    headers={
        "X-Shop-API-Key": os.environ["NEUROON_API_KEY"],
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()

Errores

Código	Mensaje típico	Causa
`401`	`Invalid or missing API Key`	Falta `X-Shop-API-Key` o el formato no es `sk_*`
`403`	`Origin mismatch — API Key cannot be used from this domain`	El navegador llama con Origin distinto a `shop.url`
`403`	`Shop ID mismatch`	La `sk_*` no pertenece al `shopId` de la URL
`429`	`rate_limit_exceeded`	Bucket por endpoint agotado — ver Rate Limits

Próximas lecturas

Widget Token — autenticación frontend.
Rate Limits — cuotas por plan y backoff.
Errores — estructura completa.

Cabecera​

Formato​

Validación de Origin​

Origin validation: tres modos​

Generación y rotación​

Almacenamiento​

Ejemplos por stack​

cURL​

Node.js / TypeScript​

.NET / C# (cualquier .NET 6+)​

Python​

Errores​

Próximas lecturas​