API de Epinium

Acceso: Configuración → API Keys

Epinium expone tus datos por una API REST para que puedas leerlos desde tus propias herramientas: un cuadro de mando propio, un script de análisis o un asistente de IA. Es la misma información que ves en la app, con las mismas cifras.

En su versión actual la API es de solo lectura: sirve para consultar, no para modificar campañas ni productos.

¿Buscas usarla desde un asistente de IA?

No necesitas programar nada. El MCP de Epinium conecta estos mismos datos con Claude y otros asistentes compatibles.

Generar un token

1. Ve a Configuración → API Keys
2. Haz clic en Crear API key y dale un nombre que te recuerde para qué es
3. Marca los permisos que necesite
4. Copia la clave y guárdala en un sitio seguro
5. Úsala en la cabecera Authorization de cada petición

La clave solo se muestra una vez

Al crearla se ve el valor completo una única vez. Si la pierdes no se puede recuperar: hay que revocarla y crear otra.

Permisos

Cada token lleva los permisos que le marques al crearlo. Concede solo los que la integración necesite.

Permiso	Da acceso a
catalog:read	Productos, marcas, países y clusters
campaigns:read	Campañas, ad groups, targets, product ads y términos de búsqueda
workflows:read	Tus workflows, su configuración y a qué campañas llegan
connections:read	Las conexiones de Amazon de tu cuenta
tasks:read	Tareas de Epinium y sus items
skills:read	El catálogo de playbooks de marketing validados de Epinium

Un token alcanza todas las conexiones de tu cuenta. Si eres una agencia, alcanza las conexiones que cada cliente te haya compartido al aceptar tu invitación.

Si eres una agencia: elige la cuenta en cada llamada

Un token de agencia alcanza varias cuentas, así que cada petición tiene que decir sobre cuál opera. Con la cabecera Epinium-Account: <id de la cuenta>, o con el parámetro account_id si llamas desde el MCP.

/v1/me y /v1/accounts son la excepción: responden sin elegir cuenta, y son precisamente los que te dicen qué cuentas alcanzas y cómo se llaman.

Elegida la cuenta, la ves entera: sus productos y campañas se acotan a las conexiones que te compartió, y sus recursos de cuenta —workflows, tareas y clusters, que no cuelgan de ninguna conexión— se acotan a la cuenta. Lo que no está en tu alcance no se filtra en silencio: un account_id que no tengas invitado devuelve un error explícito, no una lista vacía.

Qué endpoints cubre

Cada recurso tiene un listado, y la mayoría permite además recuperar un elemento por su id. Los recursos de métricas solo tienen listado: una fila agregada sobre un rango de fechas no tiene identificador propio.

Catálogo — catalog:read

Endpoint	Qué devuelve
/v1/products	Tus productos unificados
/v1/amazon-seller-products	La vista de Seller Central de cada producto
/v1/amazon-vendor-products	La vista de Vendor Central
/v1/amazon-advertising-products	La vista de Advertising
/v1/seller-product-metrics	Ventas, sesiones, Buy Box y rank por producto
/v1/vendor-product-metrics	Ventas de Vendor por producto, con manufacturing y sourcing
/v1/product-brands	Tus marcas
/v1/countries	Países y marketplaces
/v1/clusters	Tus segmentaciones de keywords

Publicidad — campaigns:read

Endpoint	Qué devuelve
/v1/campaigns	Tus campañas de Amazon Advertising
/v1/campaign-metrics	Gasto, ventas, ACOS y ROAS por campaña
/v1/adgroups	Los ad groups de cada campaña
/v1/adgroup-metrics	Rendimiento por ad group
/v1/targets	Keywords y targets de producto
/v1/target-metrics	Rendimiento por target, con su keyword y tipo de concordancia
/v1/product-ads	El vínculo entre un ad group y el producto que anuncia
/v1/product-ad-metrics	Rendimiento por producto anunciado, con su ASIN
/v1/search-terms	Las búsquedas reales de los compradores
/v1/search-term-metrics	Rendimiento por búsqueda, con el texto y el target que la emparejó
/v1/campaigns/{id}/optimization-history	Qué cambió la automatización en una campaña, con el efecto neto

Automatización — workflows:read

Endpoint	Qué devuelve
/v1/workflows	Tus workflows, con su programación y si están activos
/v1/workflows/{id}	La configuración completa de uno: su diagrama y cada variable con su valor efectivo
/v1/workflows/{id}/campaigns	A qué campañas llega de verdad, y por qué entra cada una
/v1/workflows/{id}/performance	El rendimiento de esas campañas, con su objetivo al lado para poder juzgarlo

Un workflow puede estar programado todas las noches y no tocar ninguna campaña: /campaigns es lo que lo destapa, y cuando el conjunto sale vacío dice el motivo.

Conexiones, tareas y skills

Endpoint	Permiso	Qué devuelve
/v1/connections	connections:read	Tus conexiones de Amazon
/v1/tasks	tasks:read	Tareas de Epinium
/v1/task-items	tasks:read	Los items de cada tarea
/v1/skills	skills:read	El catálogo de playbooks de marketing de Epinium

El catálogo de skills es contenido escrito por Epinium, no datos de tu cuenta: es el mismo para todos los clientes. Qué partes de cada playbook recibes depende de tu plan.

Además, /v1/me te dice qué permisos y qué cuentas alcanza tu token. Es la primera llamada útil para comprobar que la clave funciona.

Tres reglas al leer los datos

Estas tres explican casi todas las dudas de interpretación:

• Los importes son texto, no números. "cost": "8.22" llega como cadena a propósito, para que no pierda precisión al convertirse a decimal binario.
• Los ratios van en fracción, no en porcentaje. Un ACOS del 90,83 % llega como 0.908287. Multiplica por 100 para mostrarlo.
• null no es 0. null significa que Amazon no reportó ese dato; 0 significa cero de verdad. Un acos a null es una campaña que gastó sin vender, no publicidad gratis. Y new_to_brand_sales llega a null en Sponsored Products porque Amazon no lo mide en ese formato.

Qué cambió la automatización en una campaña

/v1/campaigns/{id}/optimization-history responde qué cambió el workflow en una campaña, no qué decidió. La diferencia importa: en un historial de decisiones el mismo target puede aparecer con una subida y una bajada la misma noche, y ahí no se ve que se anulan entre sí.

Por eso cada fila viene agregada al efecto neto de la entidad: la puja de antes del primer cambio del periodo contra la de después del último, y cuántas veces se movió por el camino. Un target que subió de 0,18 € a 0,45 € y esa misma noche volvió a 0,18 € sale con un neto de cero y dos movimientos — que es la lectura útil, y justo la que un listado esconde.

Tres cosas delimitan lo que devuelve:

• Solo cambios reales. Las simulaciones no se exponen aquí, ni con ningún parámetro: son pujas que nunca llegaron a Amazon.
• Solo lo aplicado, no lo propuesto. El optimizador calcula una puja que después un tope puede recortar; solo se reporta lo que se envió.
• Ventana máxima de 90 días. Es lo que se conservan estos registros. Sin fechas, devuelve los últimos 90 días.

Los cambios que no son de puja —keywords cosechadas, negativos, ajustes de emplazamiento, targets en cuarentena o bloqueados— van contados aparte en other_changes, porque no tienen una puja anterior con la que compararse.

Límites

• Las métricas exigen un rango de fechas. start_date y end_date son obligatorios en todos los recursos de métricas.
• El rango tiene un máximo, y depende de la granularidad. Con granularity=total, 366 días; con granularity=daily, 93. En targets y términos de búsqueda, los recursos más pesados, bajan a 93 y 31. Pedir más devuelve un error diciendo el límite exacto. Ambas fechas entran en el rango.
• Los listados se paginan de dos formas. Los recursos de catálogo y estructura usan un cursor (starting_after); los de métricas usan limit y offset. En ambos casos, has_more te dice si queda otra página.
• Hay un límite de peticiones por token. Si lo superas recibes un 429 y basta con reintentar más despacio.
• También hay un límite de peticiones simultáneas. Un 429 puede significar "demasiadas a la vez", no solo "demasiadas por minuto"; y un 503 significa que el servidor está saturado en ese momento. Los dos traen Retry-After y los dos son transitorios: reintenta con menos peticiones en paralelo.
• Una respuesta no puede expandir más de 5.000 objetos. expand sobre listas —los productos de un clúster, los países de una conexión— multiplica en cada nivel. Si te pasas recibes un 400 diciendo cuántos objetos habría devuelto: baja el limit, quita algún expand, o pide esos datos a su propio endpoint.

Créditos

Las llamadas a esta API consumen créditos de tu cuenta. Cuánto cuesta cada recurso lo puedes ver en la aplicación, en Configuración → Créditos.

Cada respuesta te dice lo que has gastado:

Cabecera	Qué es
X-Epinium-Credits-Cost	Lo que ha costado esta llamada
X-Epinium-Credits-Remaining	Lo que te queda. Es aproximado: si tienes otras cosas consumiendo a la vez, puede desviarse
X-Epinium-Credits-Breakdown	El desglose, por recurso y precio unitario: product=100x1,country=100x0
X-Epinium-Credits-Max	Lo máximo que podía costar, calculado antes de ejecutarla

Dos cosas que conviene saber:

• Solo se cobra lo que se entrega. Una llamada que falla no consume nada, y un expand que no devuelve datos —porque tu token no tiene ese permiso, o el dato es de otra cuenta— tampoco.
• En métricas lo que cuesta es el rango de fechas, no el número de filas. Pedir un año con limit=1 no es barato: el coste va por cada día del rango, porque es lo que hay que leer para responder, con un mínimo de 3 días por llamada. Si quieres gastar menos, acorta el rango.

Si no te llegan los créditos recibes un 402 antes de ejecutar la llamada: nunca te vas a encontrar con media respuesta. Y no te dice solo que no llega, te dice qué cambiar y a qué valor:

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_credits",
    "message": "insufficient credits: needs up to 366 (campaignMetrics=1x1,campaignMetrics:window=365x1), 120 available. Shorten the date range to 119 days or less.",
    "param": "end_date"
  }
}

El param es el mismo remedio legible por máquina: limit, end_date o include_total. Si viene sin param, no hay ningún parámetro que arregle la llamada y hay que recargar.

Parámetros y respuestas de cada endpoint

La tabla anterior dice qué recursos hay. Para ver los parámetros de entrada y la forma exacta de cada respuesta, hay dos caminos:

• Referencia navegable — cada endpoint con sus parámetros, sus tipos y un ejemplo de respuesta. Se genera desde la propia API, así que no puede quedarse desactualizada. Está en inglés.
• Esquema OpenAPI — el documento OpenAPI 3.0 en crudo, para importarlo en Postman, Insomnia o un generador de clientes. No necesita token.